From f7b4088df8cd59238c797aceba0ab6e160cbebcb Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 4 Nov 2022 16:28:03 +0100 Subject: [PATCH 1/4] docs: Setup external PostgreSQL server --- docs/install/database.md | 88 ++++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 5 +++ 2 files changed, 93 insertions(+) create mode 100644 docs/install/database.md diff --git a/docs/install/database.md b/docs/install/database.md new file mode 100644 index 0000000000000..c070cfbb0c429 --- /dev/null +++ b/docs/install/database.md @@ -0,0 +1,88 @@ +## Recommendation + +For production deployments, we recommend using an external [PostgreSQL](https://www.postgresql.org/) database (version 13 or higher). + +## Basic configuration + +Before starting the Coder server, prepare the database server. Create a role and a database. +Remember that the role must have access to the created database. + +With `psql`: + +```sql +CREATE ROLE coder LOGIN SUPERUSER PASSWORD 'secret42'; +``` + +With `psql -U coder`: + +```sql +CREATE DATABASE coder; +``` + +Coder configuration is defined via [environment variables](../admin/configure.md). +The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable. + +```sh +export CODER_PG_CONNECTION_URL="postgres://coder@localhost/coder?password=secret42&sslmode=disable" +``` + +## Custom schema + +For installations with elevated security requirements, it's advised to use a separate [schema](https://www.postgresql.org/docs/current/ddl-schemas.html) instead of the public one. + +With `psql -U coder`: + +```sql +CREATE SCHEMA myschema; +``` + +Once the schema is created, you can list all schemas with `\dn`: + +``` + List of schemas + Name | Owner +-----------+---------- + myschema | coder + public | postgres +(2 rows) +``` + +In this case the database client requires the modified connection string: + +```sh +export CODER_PG_CONNECTION_URL="postgres://coder@localhost/coder?password=secret42&sslmode=disable&search_path=myschema" +``` + +The `search_path` parameter determines the order of schemas in which they are visited while looking for a specific table. +The first schema named in the search path is called the current schema. By default `search_path` defines the following schemas: + +```sql +SHOW search_path; + +search_path +-------------- + "$user", public +``` + +Using the `search_path` in the connection string corresponds to the following `psql` command: + +```sql +SET search_path TO myschema; +``` + +## Troubleshooting + +### Coder server fails startup with "current_schema: converting NULL to string is unsupported" + +Please make sure that the schema selected in the connection string `...&search_path=myschema` exists +and the role has granted permissions to access it. The schema should be present on this listing: + +```sh +psql -U coder -c '\dn' +``` + +## Next steps + +- [Quickstart](../quickstart.md) +- [Configuring Coder](../admin/configure.md) +- [Templates](../templates.md) diff --git a/docs/manifest.json b/docs/manifest.json index 40d03779a0a45..3dceea40cc632 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -55,6 +55,11 @@ "description": "Run Coder in offline / air-gapped environments", "path": "./install/offline.md" }, + { + "title": "External database", + "description": "Use external PostgreSQL database", + "path": "./install/database.md" + }, { "title": "Uninstall", "description": "Learn how to uninstall Coder", From 699a8c95366ef88ffadc285124391b6c7a0fa28a Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 4 Nov 2022 18:04:22 +0100 Subject: [PATCH 2/4] Update docs/install/database.md Co-authored-by: Mathias Fredriksson --- docs/install/database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/database.md b/docs/install/database.md index c070cfbb0c429..28936c8c85490 100644 --- a/docs/install/database.md +++ b/docs/install/database.md @@ -4,7 +4,7 @@ For production deployments, we recommend using an external [PostgreSQL](https:// ## Basic configuration -Before starting the Coder server, prepare the database server. Create a role and a database. +Before starting the Coder server, prepare the database server by creating a role and a database. Remember that the role must have access to the created database. With `psql`: From 800cff299ae7cfc6c9dde6551ebb0edd168c298d Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 4 Nov 2022 18:15:41 +0100 Subject: [PATCH 3/4] Use user:password pattern --- docs/install/database.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install/database.md b/docs/install/database.md index 28936c8c85490..5989f7e9e8d98 100644 --- a/docs/install/database.md +++ b/docs/install/database.md @@ -23,7 +23,7 @@ Coder configuration is defined via [environment variables](../admin/configure.md The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable. ```sh -export CODER_PG_CONNECTION_URL="postgres://coder@localhost/coder?password=secret42&sslmode=disable" +export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable" ``` ## Custom schema @@ -50,7 +50,7 @@ Once the schema is created, you can list all schemas with `\dn`: In this case the database client requires the modified connection string: ```sh -export CODER_PG_CONNECTION_URL="postgres://coder@localhost/coder?password=secret42&sslmode=disable&search_path=myschema" +export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable&search_path=myschema" ``` The `search_path` parameter determines the order of schemas in which they are visited while looking for a specific table. From 1bf6478e4a054aff02bebfe7d12e8ee9362b66e3 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 4 Nov 2022 18:23:48 +0100 Subject: [PATCH 4/4] Fix --- docs/install/database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/database.md b/docs/install/database.md index 5989f7e9e8d98..1b3886c4ce285 100644 --- a/docs/install/database.md +++ b/docs/install/database.md @@ -67,7 +67,7 @@ search_path Using the `search_path` in the connection string corresponds to the following `psql` command: ```sql -SET search_path TO myschema; +ALTER ROLE coder SET search_path = myschema; ``` ## Troubleshooting