From 3d1d115a309e69e63f0446a03cbe4ff2567eec3d Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 17 Mar 2022 15:52:23 +0100 Subject: [PATCH 1/5] docs: add more content around database connections --- website/docs/deploy/configuring-unleash.md | 81 +++++++++++++++++++++- 1 file changed, 78 insertions(+), 3 deletions(-) diff --git a/website/docs/deploy/configuring-unleash.md b/website/docs/deploy/configuring-unleash.md index 65fb23dca8..c2bd131baf 100644 --- a/website/docs/deploy/configuring-unleash.md +++ b/website/docs/deploy/configuring-unleash.md @@ -203,7 +203,82 @@ function getLogger(name) { The logger interface with its `debug`, `info`, `warn` and `error` methods expects format string support as seen in `debug` or the JavaScript `console` object. Many commonly used logging implementations cover this API, e.g., bunyan, pino or winston. -## Database pooling connection timeouts {#database-pooling-connection-timeouts} +## Database configuration -- Please be aware of the default values of connection pool about idle session handling. -- If you have a network component which closes idle sessions on tcp layer, please ensure, that the connection pool idleTimeoutMillis setting is lower than the timespan as the network component will close the idle connection. +You cannot run the Unleash server without a database. You must provide Unleash with database connection details for it to start correctly. + +The available options are listed in the table below. Options can be specified either via JavaScript (only when starting Unleash via code) or via environment variables. The "property name" column below gives the name of the property on the Unleash options' `db` object: + +| Property name | Environment variable | Default value | Description | +|--------------------------|---------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `user` | `DATABASE_USERNAME` | `unleash_user` | The database username. | +| `password` | `DATABASE_PASSWORD` | `passord` | The database password. | +| `host` | `DATABASE_HOST` | `localhost` | The database hostname. | +| `port` | `DATABASE_PORT` | `5432` | The database port. | +| `database` | `DATABASE_NAME` | `unleash` | The name of the database. | +| `ssl` | `DATABASE_SSL` | N/A | An object describing SSL options. In code, provide a regular JavaScript object. When using the environment variable, provide a **stringified JSON object**. | +| `pool` | N/A (use the below variables) | | An object describing database pool options. With environment variables, use the options below directly. | +| `pool.min` | `DATABASE_POOL_MIN` | 0 | The minimum number of connections in the connection pool. | +| `pool.max` | `DATABASE_POOL_MAX` | 4 | The maximum number of connections in the connection pool. | +| `pool.idleTimeoutMillis` | `DATABASE_POOL_IDLE_TIMEOUT_MS` | 30000 | The amount of time (in milliseconds) that a connection must be idle for before it is marked as a candidate for eviction. | +| | `DATABASE_URL` | N/A | A string that matches the [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING), such as `postgres://USER:PASSWORD@HOST:PORT/DATABASE`. | +| | `DATABASE_URL_FILE` | N/A | The path to a file that contains a [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). | + + +Below is an example configuration in JavaScript showing the default options: + + +``` js +const unleashOptions = { + db: { + user: 'unleash_user', + password: 'passord', + host: 'localhost', + port: 5432, + database: 'unleash', + ssl: false, + pool: { + min: 0, + max: 4, + idleTimeoutMillis: 30000, + }, + }, +}; +``` + +### `db.ssl` vs `DATABASE_SSL` options + +When initializing Unleash from code, you'll provide the `db.ssl` option as a JavaScript object. As such, any functions will get evaluated before the object is used for configuration. When using the `DATABASE_SSL` environment variable, you must provide the value as a stringified JSON object. The object will get parsed before being used for configuration, but no further evaluation will take place. + +If you want to read content from a file, you should either initialize Unleash via JavaScript or manually interpolate the required values into the environment variable: + +<> + +``` js title="Reading from the file system in JavaScript" +// assuming this is part of the `db` config property +{ + ssl: { + key: fs.readFileSync('/path/to/client-key/postgresql.key').toString(), + // other properties omitted for brevity + } +} +``` + +``` bash title="Reading from the file system with bash" +DATABASE_SSL="{ \"key\": \"$(cat /path/to/client-key/postgresql.key)\" }" +``` + +### Enabling self-signed certificates + +To use self-signed certificates, you should set the SSL property `rejectUnauthorized` to `false` and set the `ca` property to the value of the certificate: + + +### Supported Postgres SSL modes + +Unleash builds directly on the [node-postgres library](https://node-postgres.com/features/ssl), so we support all the same SSL modes that they support. As of version 8 (released on February 25th 2020), [node-postgres no longer supports all sslmodes](https://node-postgres.com/announcements#2020-02-25). For this reason, Unleash cannot support all of Postgres' SSL modes. Specifically, Unleash **does not support** `sslmode=prefer`. Instead you must know whether you require an SSL connection ahead of time. + +### Troubleshooting: database pooling connection timeouts {#database-pooling-connection-timeouts} + +- Check the default values of connection pool about idle session handling. + +- If you have a network component which closes idle sessions on the TCP layer, make sure that the connection pool's `idleTimeoutMillis` setting is lower than the `timespan` setting. If it isn't, then the network component will close the connection. From b235eba6ac92dea019c2e2ed60422ab2a5858109 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 17 Mar 2022 16:11:56 +0100 Subject: [PATCH 2/5] docs: add code samples, move db configuration to separate section --- website/docs/deploy/configuring-unleash.md | 78 ++++++++++++++++------ 1 file changed, 56 insertions(+), 22 deletions(-) diff --git a/website/docs/deploy/configuring-unleash.md b/website/docs/deploy/configuring-unleash.md index c2bd131baf..a5b756a51c 100644 --- a/website/docs/deploy/configuring-unleash.md +++ b/website/docs/deploy/configuring-unleash.md @@ -2,25 +2,17 @@ id: configuring_unleash title: Configuring Unleash --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + > This is the guide on how to configure **Unleash v4 self-hosted**. If you are still using Unleash v3 you should checkout [configuring Unleash v3](./configuring_unleash_v3) ## Must configure -### Database details {#database-details} +### Database -In order for Unleash server to work, you must setup database connection details. - -- If using docker, use environment variables - - `DATABASE_HOST` - the database hostname - defaults to `localhost` - - `DATABASE_PORT` - the port the database is listening on - defaults to `5432` - - `DATABASE_USERNAME` - the user configured for access - defaults to `unleash_user` - - `DATABASE_PASSWORD` - the password for the user - defaults to `passord` (the Norwegian word for _password_) - - `DATABASE_NAME` - the name of the database - defaults to `unleash` - - `DATABASE_SSL` - a json object representing SSL configuration or `false` for not using SSL - - `DATABASE_SCHEMA` - Which schema to use - defaults to `public` -- We also support `DATABASE_URL` see [libpq's doc](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) for full format explanation. In short: `postgres://USER:PASSWORD@HOST:PORT/DATABASE` -- If you're using secret files from kubernetes and would like to load a `DATABASE_URL` format from a file, use `DATABASE_URL_FILE` and point it to a path containing a connection URL. +In order for Unleash server to work, you need a running database and its connection details. See the [database configuration section](#database-configuration) for the available options and configuration details. ## Nice to configure @@ -252,26 +244,68 @@ When initializing Unleash from code, you'll provide the `db.ssl` option as a Jav If you want to read content from a file, you should either initialize Unleash via JavaScript or manually interpolate the required values into the environment variable: -<> + + + ``` js title="Reading from the file system in JavaScript" -// assuming this is part of the `db` config property -{ - ssl: { - key: fs.readFileSync('/path/to/client-key/postgresql.key').toString(), - // other properties omitted for brevity - } -} +const unleashOptions = { + db: { + // other options omitted for brevity + ssl: { + ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(), + } + }} ``` + + + + ``` bash title="Reading from the file system with bash" -DATABASE_SSL="{ \"key\": \"$(cat /path/to/client-key/postgresql.key)\" }" +DATABASE_SSL="{ \"key\": \"$(cat /path/to/server-certificates/root.crt)\" }" ``` + + + + + + ### Enabling self-signed certificates + To use self-signed certificates, you should set the SSL property `rejectUnauthorized` to `false` and set the `ca` property to the value of the certificate: + + + + +``` js title="Enable self-signed certificates" +const unleashOptions = { + db: { + // other options omitted for brevity + ssl: { + rejectUnauthorized: false, + ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(), + } + }} + +``` + + + + + +``` bash title="Enable self-signed certificates" +DATABASE_SSL="{ \"rejectUnauthorized\": false, \"key\": \"$(cat /path/to/server-certificates/root.crt)\" }" +``` + + + + + +Visit [the node-postgres library's SSL section](https://node-postgres.com/features/ssl) for more information. ### Supported Postgres SSL modes From b8673c86b184f889d7faa502195feef3e5beb2b8 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 17 Mar 2022 16:43:19 +0100 Subject: [PATCH 3/5] docs: remove duplicate db connection options description --- website/docs/deploy/configuring-unleash.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/website/docs/deploy/configuring-unleash.md b/website/docs/deploy/configuring-unleash.md index a5b756a51c..f1e3852ec9 100644 --- a/website/docs/deploy/configuring-unleash.md +++ b/website/docs/deploy/configuring-unleash.md @@ -83,19 +83,7 @@ unleash.start(unleashOptions); You can also use the environment variables `INIT_ADMIN_API_TOKENS` or `INIT_CLIENT_API_TOKENS` to create API admin or client tokens on startup. Both variables require a comma-separated list of API tokens to initialize (for instance `*:*.some-random-string, *:*.some-other-token`). The tokens found in `INIT_ADMIN_API_TOKENS` and `INIT_CLIENT_API_TOKENS` will be created as admin and client tokens respectively and Unleash will assign a username automatically. - **databaseUrl** - (_deprecated_) the postgres database url to connect to. Only used if _db_ object is not specified, and overrides the _db_ object and any environment variables that change parts of it (like `DATABASE_SSL`). Should include username/password. This value may also be set via the `DATABASE_URL` environment variable. Alternatively, if you would like to read the database url from a file, you may set the `DATABASE_URL_FILE` environment variable with the full file path. The contents of the file must be the database url exactly. -- **db** - The database configuration object taking the following properties: - - _user_ - the database username (`DATABASE_USERNAME`) - - _password_ - the database password (`DATABASE_PASSWORD`) - - _host_ - the database hostname (`DATABASE_HOST`) - - _port_ - the database port defaults to 5432 (`DATABASE_PORT`) - - _database_ - the database name to be used (`DATABASE_NAME`) - - _ssl_ - an object describing ssl options, see https://node-postgres.com/features/ssl (`DATABASE_SSL`, as a stringified json object) - - _schema_ - the postgres database schema to use. Defaults to 'public'. (`DATABASE_SCHEMA`) - - _version_ - the postgres database version. Used to connect a non-standard database. Defaults to `undefined`, which let the underlying adapter to detect the version automatically. (`DATABASE_VERSION`) - - _pool_ - an object describing pool options, see https://knexjs.org/#Installation-pooling. We support the following three fields: - - _min_ - minimum connections in connections pool (defaults to 0) (`DATABASE_POOL_MIN`) - - _max_ - maximum connections in connections pool (defaults to 4) (`DATABASE_POOL_MAX`) - - _idleTimeoutMillis_ - time in milliseconds a connection must be idle before being marked as a candidate for eviction (defaults to 30000) (`DATABASE_POOL_IDLE_TIMEOUT_MS`) +- **db** - The database configuration object. See [the database configuration section](#database-configuration) for a full overview of the available properties. - **disableLegacyFeaturesApi** (boolean) - whether to disable the [legacy features API](../api/admin/feature-toggles-api.md). Defaults to `false` (`DISABLE_LEGACY_FEATURES_API`). Introduced in Unleash 4.6. - **email** - the email object configuring an SMTP server for sending welcome mails and password reset mails - `host` - The server URL to your SMTP server From da0fe218320718f198433a6b69a524d1a81f5208 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 22 Mar 2022 11:19:09 +0100 Subject: [PATCH 4/5] docs: PR feedback: configure db url, db url file, precedence --- website/docs/deploy/configuring-unleash.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/website/docs/deploy/configuring-unleash.md b/website/docs/deploy/configuring-unleash.md index f1e3852ec9..10b6a32243 100644 --- a/website/docs/deploy/configuring-unleash.md +++ b/website/docs/deploy/configuring-unleash.md @@ -185,9 +185,13 @@ The logger interface with its `debug`, `info`, `warn` and `error` methods expect ## Database configuration +:::info +In-code configuration values take precedence over environment values: If you provide a database username both via environment variables and in code with the Unleash options object, Unleash will use the in-code username. +::: + You cannot run the Unleash server without a database. You must provide Unleash with database connection details for it to start correctly. -The available options are listed in the table below. Options can be specified either via JavaScript (only when starting Unleash via code) or via environment variables. The "property name" column below gives the name of the property on the Unleash options' `db` object: +The available options are listed in the table below. Options can be specified either via JavaScript (only when starting Unleash via code) or via environment variables. The "property name" column below gives the name of the property on the Unleash options' `db` object. | Property name | Environment variable | Default value | Description | |--------------------------|---------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -201,12 +205,16 @@ The available options are listed in the table below. Options can be specified ei | `pool.min` | `DATABASE_POOL_MIN` | 0 | The minimum number of connections in the connection pool. | | `pool.max` | `DATABASE_POOL_MAX` | 4 | The maximum number of connections in the connection pool. | | `pool.idleTimeoutMillis` | `DATABASE_POOL_IDLE_TIMEOUT_MS` | 30000 | The amount of time (in milliseconds) that a connection must be idle for before it is marked as a candidate for eviction. | -| | `DATABASE_URL` | N/A | A string that matches the [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING), such as `postgres://USER:PASSWORD@HOST:PORT/DATABASE`. | -| | `DATABASE_URL_FILE` | N/A | The path to a file that contains a [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). | + +Alternatively, you can use a [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) to connect to the database. You can provide it directly or from a file by using one of the below options. In JavaScript, these are top-level properties of the root configuration object, *not* the `db` object. + +| Property name | Environment variable | Default value | Description | +|-------------------|----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `databaseUrl` | `DATABASE_URL` | N/A | A string that matches the [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING), such as `postgres://USER:PASSWORD@HOST:PORT/DATABASE`. | +| `databaseUrlFile` | `DATABASE_URL_FILE` | N/A | The path to a file that contains a [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). | -Below is an example configuration in JavaScript showing the default options: - +Below is an example JavaScript configuration object. ``` js const unleashOptions = { @@ -223,6 +231,8 @@ const unleashOptions = { idleTimeoutMillis: 30000, }, }, + databaseUrl: "postgres:/USER:PASSWORD@HOST:PORT/DATABASE", + databaseUrlFile: "/path/to/file", }; ``` From 47a4fe32342ffcda2fc1c276a04accf23fdde713 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 22 Mar 2022 11:20:48 +0100 Subject: [PATCH 5/5] docs: sort options alphabetically in example object. --- website/docs/deploy/configuring-unleash.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/deploy/configuring-unleash.md b/website/docs/deploy/configuring-unleash.md index 10b6a32243..b6701a3d17 100644 --- a/website/docs/deploy/configuring-unleash.md +++ b/website/docs/deploy/configuring-unleash.md @@ -218,6 +218,8 @@ Below is an example JavaScript configuration object. ``` js const unleashOptions = { + databaseUrl: "postgres:/USER:PASSWORD@HOST:PORT/DATABASE", + databaseUrlFile: "/path/to/file", db: { user: 'unleash_user', password: 'passord', @@ -231,8 +233,6 @@ const unleashOptions = { idleTimeoutMillis: 30000, }, }, - databaseUrl: "postgres:/USER:PASSWORD@HOST:PORT/DATABASE", - databaseUrlFile: "/path/to/file", }; ```