From 4552f88950739e776786c38be335f5445c3e7f84 Mon Sep 17 00:00:00 2001 From: jamesread Date: Sat, 14 Sep 2024 21:50:20 +0100 Subject: [PATCH] doc: Improve config docs --- .env.example | 36 ++++++++++++-------- apps/docs/installation/development.mdx | 4 +++ apps/docs/installation/docker-compose.mdx | 14 +++++++- apps/docs/installation/docker.mdx | 34 ++++++++++++------ apps/docs/mint.json | 6 ++++ apps/docs/snippets/docker-envvar-apps.mdx | 13 ++++--- apps/docs/snippets/docker-envvar-general.mdx | 15 ++++++++ 7 files changed, 91 insertions(+), 31 deletions(-) create mode 100644 apps/docs/snippets/docker-envvar-general.mdx diff --git a/.env.example b/.env.example index 7ef00fa5..5b70c78c 100644 --- a/.env.example +++ b/.env.example @@ -1,4 +1,6 @@ -# Required Settings +# Configuration reference: http://docs.postiz.com/configuration/reference + +# === Required Settings DATABASE_URL="postgresql://postiz-user:postiz-password@localhost:5432/postiz-db-local" REDIS_URL="redis://localhost:6379" JWT_SECRET="random string for your JWT secret, make it long" @@ -6,11 +8,19 @@ FRONTEND_URL="http://localhost:4200" NEXT_PUBLIC_BACKEND_URL="http://localhost:3000" BACKEND_INTERNAL_URL="http://localhost:3000" -# Optional. Your upload directory path if you host your files locally. -UPLOAD_DIRECTORY="/opt/postiz/uploads/" +## These are dummy values, you must create your own from Cloudflare. +## Remember to set your public internet IP address in the allow-list for the API token. +## +## Cloudflare is currently required to save things like social media avatars for accounts. +CLOUDFLARE_ACCOUNT_ID="QhcMSXQyPuMCRpSQcSYdEuTYgHeCXHbu" +CLOUDFLARE_ACCESS_KEY="dcfCMSuFEeCNfvByUureMZEfxWJmDqZe" +CLOUDFLARE_SECRET_ACCESS_KEY="zTTMXBmtyLPwHEdpACGHgDgzRTNpTJewiNriLnUS" +CLOUDFLARE_BUCKETNAME="postiz" +CLOUDFLARE_BUCKET_URL="https://QhcMSXQyPuMCRpSQcSYdEuTYgHeCXHbu.r2.cloudflarestorage.com/" +CLOUDFLARE_REGION="auto" -# Optional: your upload directory slug if you host your files locally. -NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY="/opt/postiz/uploads/" + +# === Common optional Settings ## This is a dummy key, you must create your own from Resend. ## If this variable exists, user activation is required. @@ -19,14 +29,12 @@ NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY="/opt/postiz/uploads/" #EMAIL_FROM_ADDRESS="" #EMAIL_FROM_NAME="" -## These are dummy values, you must create your own from Cloudflare. -## Remember to set your public internet IP address in the allow-list for the API token. -CLOUDFLARE_ACCOUNT_ID="QhcMSXQyPuMCRpSQcSYdEuTYgHeCXHbu" -CLOUDFLARE_ACCESS_KEY="dcfCMSuFEeCNfvByUureMZEfxWJmDqZe" -CLOUDFLARE_SECRET_ACCESS_KEY="zTTMXBmtyLPwHEdpACGHgDgzRTNpTJewiNriLnUS" -CLOUDFLARE_BUCKETNAME="postiz" -CLOUDFLARE_BUCKET_URL="https://QhcMSXQyPuMCRpSQcSYdEuTYgHeCXHbu.r2.cloudflarestorage.com/" -CLOUDFLARE_REGION="auto" +# Your upload directory path if you host your files locally, otherwise Cloudflare will be used. +#UPLOAD_DIRECTORY="/opt/postiz/uploads/" + +# Your upload directory path if you host your files locally, otherwise Cloudflare will be used. +#NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY="/opt/postiz/uploads/" + # Social Media API Settings X_API_KEY="" @@ -57,7 +65,7 @@ DRIBBBLE_CLIENT_SECRET="" # Misc Settings OPENAI_API_KEY="" NEXT_PUBLIC_DISCORD_SUPPORT="" -NEXT_PUBLIC_POLOTNO="Polotno key for the gallery" +NEXT_PUBLIC_POLOTNO="" # Payment settings FEE_AMOUNT=0.05 diff --git a/apps/docs/installation/development.mdx b/apps/docs/installation/development.mdx index a5b2dc62..015b9bf1 100644 --- a/apps/docs/installation/development.mdx +++ b/apps/docs/installation/development.mdx @@ -72,6 +72,10 @@ git clone https://github.com/gitroomhq/gitroom Copy the `.env.example` file to `.env` and fill in the values +An example file of the most used configuration settings can be found here; [example postiz.env file](https://raw.githubusercontent.com/gitroomhq/postiz-app/main/.env.example) + +There is also a [configuration reference](/configuration/reference) page that goes into more detail. + ```bash .env # Required Settings DATABASE_URL="postgresql://postiz-user:postiz-password@localhost:5432/postiz-db-local" diff --git a/apps/docs/installation/docker-compose.mdx b/apps/docs/installation/docker-compose.mdx index d4e009b7..8c422f01 100644 --- a/apps/docs/installation/docker-compose.mdx +++ b/apps/docs/installation/docker-compose.mdx @@ -4,9 +4,14 @@ title: Docker Compose import EarlyDoc from '/snippets/earlydoc.mdx'; import DockerEnvvarApps from '/snippets/docker-envvar-apps.mdx'; +import DockerEnvvarGeneral from '/snippets/docker-envvar-general.mdx'; + + +The container images will copy a file called `/config/postiz.env` to `/apps/.env` on startup. + # Example `docker-compose.yml` file ```yaml @@ -15,8 +20,15 @@ services: image: ghcr.io/gitroomhq/postiz-app:latest container_name: postiz restart: always + environment: # If you want to specify the variables in your compose file. + - DATABASE_URL="postgresql://postiz-user:postiz-password@localhost:5432/postiz-db-local" + - REDIS_URL="redis://localhost:6379" + - JWT_SECRET="random string for your JWT secret, make it long" + - FRONTEND_URL="http://localhost:4200" + - NEXT_PUBLIC_BACKEND_URL="http://localhost:3000" + - BACKEND_INTERNAL_URL="http://localhost:3000" volumes: - - ./config:/config/ # Should contain your .env file + - ./config:/config/ # If you want to specify the variables in your `postiz.env` file. ports: - 4200:4200 - 3000:3000 diff --git a/apps/docs/installation/docker.mdx b/apps/docs/installation/docker.mdx index 154cdea6..3ba5228b 100644 --- a/apps/docs/installation/docker.mdx +++ b/apps/docs/installation/docker.mdx @@ -4,24 +4,36 @@ title: Docker import EarlyDoc from '/snippets/earlydoc.mdx'; import DockerEnvvarApps from '/snippets/docker-envvar-apps.mdx'; +import DockerEnvvarGeneral from '/snippets/docker-envvar-general.mdx'; -# Set environment variables + -Postiz configuration is entirely via environment variables for now. You might be used to setting environment variables when starting containers, -however postiz needs a LOT of environment variables, so setting these on command line or in a docker-compose is probably not practical for long -term maintainability. - -It is recommended to use a `.env` file, which the Postiz containers look for in /config. Docker will automatically create this file for you on a -docker volume the first time you start up Postiz. - -The default .env file can be found here; [example .env file](https://raw.githubusercontent.com/gitroomhq/postiz-app/main/.env.example) +The container images will copy a file called `/config/postiz.env` to `/apps/.env` on startup. # Create the container on command line -```bash -docker create --name postiz -v ./config:/config -p 4200:4200 -p 3000:3000 ghcr.io/gitroomhq/postiz-app:latest +It is recommended to have a local directory where you save your `postiz.env` file, such as `/myContainers/postiz/config`, which is mounted as a volume. + +```bash Using a configuration volume +docker create --name postiz -v /myContainers/postiz/config:/config -p 4200:4200 -p 3000:3000 ghcr.io/gitroomhq/postiz-app:latest ``` +Alternatively, you can specify the variables one by one at creation time. This approach is not recommended +simply because it's a pain to manage, and sensitive keys get stored with the container definition, which is bad practice. + +```bash At creation-time (not recommended) +docker create --name postiz \ + -e DATABASE_URL=postgres://... \ + -e REDIS_URL=redis:// \ + -e JWT_SECRET \ + ... \ + -p 4200:4200 \ + -p 3000:3000 \ + ghcr.io/gitroomhq/postiz-app:latest +``` + + + diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 7fa169e0..4b375a4d 100644 --- a/apps/docs/mint.json +++ b/apps/docs/mint.json @@ -70,6 +70,12 @@ "installation/kubernetes-helm" ] }, + { + "group": "Configuration", + "pages": [ + "configuration/reference" + ] + }, "howitworks", "emails", "github", diff --git a/apps/docs/snippets/docker-envvar-apps.mdx b/apps/docs/snippets/docker-envvar-apps.mdx index 967daf40..314aeaa5 100644 --- a/apps/docs/snippets/docker-envvar-apps.mdx +++ b/apps/docs/snippets/docker-envvar-apps.mdx @@ -1,7 +1,10 @@ ## Controlling container services -The environment variable POSTIZ_APPS defaults to "", which means that all -services will be started in a single container. However, you can only start -specific services within the docker container by changing this environement variable. +When the environment variable `POSTIZ_APPS` is not set, or is set to an empty string, all +services will be started in a single container. This is normally fine for small, personal deployments. -For most deployments, starting all services is fine. To scale out, you might want -to start individual containers for "frontend", "backend", "worker" and "cron". +However, you can only start specific services within the docker container by changing this environement variable. + +If you need to scale, you can experiement with having multiple containers defined like; +- Frontend only: `POSTIZ_APPS="frontend"` +- Backend only: `POSTIZ_APPS="backend"` +- Worker and Cron only: `POSTIZ_APPS="worker cron"` diff --git a/apps/docs/snippets/docker-envvar-general.mdx b/apps/docs/snippets/docker-envvar-general.mdx new file mode 100644 index 00000000..cf1a0971 --- /dev/null +++ b/apps/docs/snippets/docker-envvar-general.mdx @@ -0,0 +1,15 @@ +# Set environment variables + +Postiz configuration is entirely via environment variables. + +When using Postiz container images, you can specify the environment variables when you create the container (`docker create -e DATABASE_URL=...`), but this might be +a bit tedious, as Postiz requires quite a few variables set to startup. + +It is recommended to use a `postiz.env` file, which the Postiz containers look for in /config. Docker will automatically create this file for you on a +docker volume the first time you start up Postiz. The default container images will copy the `/config/postiz.env` to `/apps/.env` on startup. Like with +any environment variables, if you change them, you must restart the application for the changes to take effect. + +An example file of the most used configuration settings can be found here; [example postiz.env file](https://raw.githubusercontent.com/gitroomhq/postiz-app/main/.env.example) + +There is also a [configuration reference](/configuration/reference) page that goes into more detail. +