From 63d7fae0e7df3e9df26354e3ecfca16e1fdee58e Mon Sep 17 00:00:00 2001 From: beeb Date: Tue, 6 Jun 2023 08:11:31 +0200 Subject: [PATCH] docs(configuration): new captcha env variables Since Friendly Captcha is now supported, a new `CAPTCHA_PROVIDER` config variable is available. Other variables have dropped the `H` as the first character. --- content/docs/configuration.md | 87 ++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 41 deletions(-) diff --git a/content/docs/configuration.md b/content/docs/configuration.md index a4dc606..a678b9a 100644 --- a/content/docs/configuration.md +++ b/content/docs/configuration.md @@ -10,66 +10,71 @@ When self-hosting Keila, you can configure most aspects of the application with environment variables. ## Database + Configure the PostgreSQL database used by Keila: -| Variable | Required | Default | Description | -| ---------------- | -------- | ------- | --------------------------------------- | -| `DB_URL` | yes | - | URL following the schema `postgres://user:password@host/database` | -| `DB_ENABLE_SSL` | no | - | Use SSL/TLS for the database connection | +| Variable | Required | Default | Description | +| --------------- | -------- | ------- | ----------------------------------------------------------------- | +| `DB_URL` | yes | - | URL following the schema `postgres://user:password@host/database` | +| `DB_ENABLE_SSL` | no | - | Use SSL/TLS for the database connection | ## Root User + When you start Keila for the first time, a root user is created. If you don’t specify otherwise, a user with a random password is created printed to stdout. -| Variable | Required | Default | Description | -| ---------------- | -------- | ------- | --------------------------------------- | +| Variable | Required | Default | Description | +| ---------------- | -------- | ---------------- | ------------------------------- | | `KEILA_USER` | | `root@localhost` | Email address for the root user | -| `KEILA_PASSWORD` | | *random* | Password for the root user | +| `KEILA_PASSWORD` | | _random_ | Password for the root user | ## URL -Configure publicly-visible URLs generated by Keila with the following variables: +Configure publicly-visible URLs generated by Keila with the following variables: -| Variable | Required | Default | Description | -| ------------- | -------- | ------- | --------------------------------------- | -| `URL_HOST` | yes | - | Domain of your Keila instance | -| `URL_PATH` | | `/` | Path of your Keila instance | -| `URL_SCHEMA` | | `http` | `http` or `https`. URL scheme of your Keila instance | -| `URL_PORT` | | `443` if `URL_SCHEMA` is `https`
value of `PORT` otherwise | Port of your Keila instance | +| Variable | Required | Default | Description | +| ------------ | -------- | ------------------------------------------------------------- | ---------------------------------------------------- | +| `URL_HOST` | yes | - | Domain of your Keila instance | +| `URL_PATH` | | `/` | Path of your Keila instance | +| `URL_SCHEMA` | | `http` | `http` or `https`. URL scheme of your Keila instance | +| `URL_PORT` | | `443` if `URL_SCHEMA` is `https`
value of `PORT` otherwise | Port of your Keila instance | ## Deployment -| Variable | Required | Default | Description | -| ---------------------- | -------- | ------- | ------------------------------ | -| `PORT` | | `4000` | Port on which Keila will listen | -| `SECRET_KEY_BASE` | yes | - | Strong secret with at least 64 characters. Can be generated with `head -c 48 /dev/urandom | base64` | -| `HASHID_SALT` | | derived from `SECRET_KEY_BASE` | Salt for creating Hashids. [More information](https://hashids.org/) | -| `DISABLE_REGISTRATION` | | `false` | Disable user registration by setting this variable to `true` | -| `DISABLE_PRECEDENCE_HEADER` | | `false` | Disable the `Precedence: Bulk` header by settings this variable to `true` | -| `USER_CONTENT_DIR` | | `./uploads` | Path to a directory where user uploads will be stored. When deploying using containers, this should point to the path of a volume to make sure uploads are persisted. | -| `USER_CONTENT_BASE_URL`| | - | Base URL at which files in `USER_CONTENT_DIR` are available on the web. It’s recommended to set up a separate server (such as Nginx or Apache) to serve user content. If not set, Keila wil serve user content files directly. | +| Variable | Required | Default | Description | +| --------------------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `PORT` | | `4000` | Port on which Keila will listen | +| `SECRET_KEY_BASE` | yes | - | Strong secret with at least 64 characters. Can be generated with `head -c 48 /dev/urandom | base64` | +| `HASHID_SALT` | | derived from `SECRET_KEY_BASE` | Salt for creating Hashids. [More information](https://hashids.org/) | +| `DISABLE_REGISTRATION` | | `false` | Disable user registration by setting this variable to `true` | +| `DISABLE_PRECEDENCE_HEADER` | | `false` | Disable the `Precedence: Bulk` header by settings this variable to `true` | +| `USER_CONTENT_DIR` | | `./uploads` | Path to a directory where user uploads will be stored. When deploying using containers, this should point to the path of a volume to make sure uploads are persisted. | +| `USER_CONTENT_BASE_URL` | | - | Base URL at which files in `USER_CONTENT_DIR` are available on the web. It’s recommended to set up a separate server (such as Nginx or Apache) to serve user content. If not set, Keila wil serve user content files directly. | ## System mailer + Keila needs to be able to send system emails, e.g. for registration and password reset emails. Configure an SMTP sender for this purpose with the following variables: -| Variable | Required | Default | Description ---- | -| ---------------------- | -------- | ------- | ---------------------------------- | -| `MAILER_TYPE` | | `smtp` | Currently only `smtp` is supported | -| `MAILER_SMTP_HOST` | yes | - | Hostname of the SMTP server | -| `MAILER_SMTP_PORT` | | `587` | Port of the SMTP server | -| `MAILER_SMTP_USER` | yes | - | Username for the SMTP server | -| `MAILER_SMTP_PASSWORD` | yes | - | Password for the SMTP server | -| `MAILER_SMTP_FROM_EMAIL` | | `MAILER_SMTP_USER` | FROM email address | - -## hCaptcha -Keila uses hCaptcha to protect your sign-up forms. Configure hCaptcha with the -following variables: - -| Variable | Required | Default | Description | -| --------------------- | -------- | ------- | ------------------------------- | -| `HCAPTCHA_SITE_KEY` | | - | hCaptcha site key | -| `HCAPTCHA_SECRET_KEY` | | `http` | hCaptcha secret key | -| `HCAPTCHA_URL` | | `https://hcaptcha.com/siteverify` | hCaptcha verification URL | \ No newline at end of file +| Variable | Required | Default | Description | +| ------------------------ | -------- | ------------------ | ---------------------------------- | +| `MAILER_TYPE` | | `smtp` | Currently only `smtp` is supported | +| `MAILER_SMTP_HOST` | yes | - | Hostname of the SMTP server | +| `MAILER_SMTP_PORT` | | `587` | Port of the SMTP server | +| `MAILER_SMTP_USER` | yes | - | Username for the SMTP server | +| `MAILER_SMTP_PASSWORD` | yes | - | Password for the SMTP server | +| `MAILER_SMTP_FROM_EMAIL` | | `MAILER_SMTP_USER` | FROM email address | + +## Captcha + +Keila can use [hCaptcha](https://www.hcaptcha.com/) or [Friendly Captcha](https://friendlycaptcha.com/) to protect your +sign-up forms. Configure the captcha provider with the following variables: + +| Variable | Required | Default | Description | +| -------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `CAPTCHA_PROVIDER` | | `hcaptcha` | Captcha provider, one of `hcaptcha` or `friendly_captcha` | +| `CAPTCHA_SITE_KEY` | | - | Captcha provider site key | +| `CAPTCHA_SECRET_KEY` | | - | Captcha provider secret key | +| `CAPTCHA_URL` | | variable | Captcha provider verification URL, defaults to `https://hcaptcha.com/siteverify` for `hcaptcha` and `https://api.friendlycaptcha.com/api/v1/siteverify` for `friendly_captcha` |