chore: add basic postgres instructions for byo databases (#2430)

docs/manifest.json

@@ -11,7 +11,14 @@
       "title": "Installation",
       "description": "How to install and deploy Coder",
       "icon": "<svg class=\"MuiSvgIcon-root jss172\" focusable=\"false\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M22.7 19l-9.1-9.1c.9-2.3.4-5-1.5-6.9-2-2-5-2.4-7.4-1.3L9 6 6 9 1.6 4.7C.4 7.1.9 10.1 2.9 12.1c1.9 1.9 4.6 2.4 6.9 1.5l9.1 9.1c.4.4 1 .4 1.4 0l2.3-2.3c.5-.4.5-1.1.1-1.4z\"></path></svg>",
-      "path": "./install.md"
+      "path": "./install.md",
+      "children": [
+        {
+          "title": "Postgres",
+          "description": "Learn how to create and use your own Postgres database.",
+          "path": "./postgres.md"
+        }
+      ]
     },
     {
       "title": "Quickstart",

docs/postgres.md

@@ -0,0 +1,95 @@
+# PostgreSQL
+
+Coder ships with a built-in PostgreSQL database, but if you'd like to set up and
+use your own, refer to the following instructions.
+
+For in-depth information, please see the [PostgreSQL
+documentation](https://www.postgresql.org/docs/current/tutorial-start.html).
+
+## Step 1: Install and start PostgreSQL
+
+### macOS with Homebrew
+
+1. Install with Homebrew:
+
+    ```console
+    brew install postgres
+    ```
+
+1. Start PostgreSQL with brew
+
+    ```console
+    brew services start postgresql
+    ```
+
+1. Connect to PostgreSQL:
+
+    ```console
+    psql postgres
+    ```
+
+### Debian/Ubuntu
+
+1. Install PostgreSQL:
+
+    ```console
+    sudo apt-get install -y postgresql
+    ```
+
+1. Start PostgreSQL:
+
+    ```console
+    sudo systemctl enable postgresql
+    sudo systemctl start postgresql
+    ```
+
+1. Connect to PostgreSQL:
+
+    ```console
+    sudo -u postgresql psql
+    ```
+
+## Step 2: Create a database and user for Coder
+
+1. Create the `coderuser` role:
+
+    ```console
+    create role coderuser with login;
+    ```
+
+1. Create a database called `coder` and assign the owner:
+
+    ```console
+    create database coder owner coder;
+    ```
+
+1. Set the password for `coderuser`:
+
+    ```console
+    \password coder # enter password when prompted
+    ```
+
+1. Assign rights to the database to your user:
+
+    ```console
+    grant all privileges on database coder to coderuser;
+    ```
+
+## Using your PostgreSQL database with Coder
+
+To use your Postgres database with Coder, provide the `CODER_PG_CONNECTION_URL`
+variable:
+
+```console
+postgresql://[user[:password]@][networkLocation][:port][/dbname][?param1=value1&...]
+```
+
+Append to `coder server` to start your deployment. For example:
+
+```console
+CODER_PG_CONNECTION_URL="postgres://<databaseUsername>@0.0.0.0/<databaseName>?sslmode=disable&password=<password>" \
+    coder server -a 0.0.0.0:3000 --verbose
+```
+
+> If you [installed Coder manually](install.md), you can add the `CODER_PG_CONNECTION_URL`
+variable to  `/etc/coder.d/coder.env`.