Improve env file documentation and add trigger for manual container b…

…uild (#2)

Co-authored-by: Benno Evers <benno@bourbaki>

.github/workflows/manually-build-containers.yaml

@@ -0,0 +1,38 @@
+name: Build and publish the repo-internal containers
+
+on:
+  workflow_call:
+    inputs:
+      docker-tag:
+        description: The tag of the generated docker containers
+        type: string
+        required: true
+
+jobs:
+  build_and_push_containers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        name: Check out code
+
+      - uses: mr-smithers-excellent/docker-build-push@v6
+        name: Build & push Docker image
+        with:
+          image: tenzir-dex
+          tags: ${{ inputs.docker-tag }}
+          registry: ghcr.io
+          directory: components/dex
+          dockerfile: components/dex/Dockerfile
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: mr-smithers-excellent/docker-build-push@v6
+        name: Build & push Docker image
+        with:
+          image: tenzir-seaweed
+          tags: ${{ inputs.docker-tag }}
+          registry: ghcr.io
+          directory: components/seaweed
+          dockerfile: components/seaweed/Dockerfile
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}

examples/onprem-integrated/docker-compose.yaml

@@ -1,6 +1,6 @@
 # Docker Compose setup for a platform deployment that integrates
-# with existing local infrastructure, eg. a dedicated auth provider and
-# a centrally managed database.
+# with existing local infrastructure, in particular a dedicated
+# auth provider.
 #
 # Assumptions:
 #
@@ -10,23 +10,17 @@
 #       TENZIR_PLATFORM_OIDC_PROVIDER_CLIENT_ID
 #       TENZIR_PLATFORM_OIDC_PROVIDER_CLIENT_SECRET
 #
-#  - An external postgres database exists and is accessible
-#    via TCP connection.
-#       TENZIR_PLATFORM_POSTGRES_USER
-#       TENZIR_PLATFORM_POSTGRES_PASSWORD
-#       TENZIR_PLATFORM_POSTGRES_HOSTNAME
-#       TENZIR_PLATFORM_POSTGRES_DB
-#
 #  - A reverse proxy is configured to terminate TLS for the
 #    domains under which the platform is reachable.
 #       TENZIR_PLATFORM_DOMAIN
 #       TENZIR_PLATFORM_CONTROL_ENDPOINT
-#       TENZIR_PLATFORM_BLOBS_ENDPOINT
+#       TENZIR_PLATFORM_DOWNLOADS_ENDPOINT
 #       TENZIR_PLATFORM_API_ENDPOINT      [only used by the CLI]
 
 services:
   platform:
     image: ghcr.io/tenzir/platform:${TENZIR_PLATFORM_VERSION:-latest}
+    restart: unless-stopped
     command: ["tenant_manager/rest/server/local.py"]
     environment:
       - BASE_PATH=
@@ -38,12 +32,13 @@ services:
       - TENANT_MANAGER_AUTH__ENABLE_SELF_SIGNED=false
       - TENANT_MANAGER_AUTH__TRUSTED_AUDIENCES=${TENZIR_PLATFORM_OIDC_TRUSTED_AUDIENCES}
       - TENANT_MANAGER_AUTH__ADMIN_FUNCTIONS=${TENZIR_PLATFORM_OIDC_ADMIN_RULES}
+      # Database backend configuration
       - STORE__TYPE=${TENZIR_PLATFORM_STORE_TYPE}
       - STORE__POSTGRES_URI=postgresql://${TENZIR_PLATFORM_POSTGRES_USER}:${TENZIR_PLATFORM_POSTGRES_PASSWORD}@${TENZIR_PLATFORM_POSTGRES_HOSTNAME}/${TENZIR_PLATFORM_POSTGRES_DB}
-      # seaweedfs connection
+      # Download button configuration
       - TENANT_MANAGER_SIDEPATH_BUCKET_NAME=${TENZIR_PLATFORM_INTERNAL_BUCKET_NAME}
       - BLOB_STORAGE__ENDPOINT_URL=http://seaweed:8333
-      - BLOB_STORAGE__PUBLIC_ENDPOINT_URL=${TENZIR_PLATFORM_BLOBS_ENDPOINT}
+      - BLOB_STORAGE__PUBLIC_ENDPOINT_URL=${TENZIR_PLATFORM_DOWNLOADS_ENDPOINT}
       - BLOB_STORAGE__ACCESS_KEY_ID=${TENZIR_PLATFORM_INTERNAL_ACCESS_KEY_ID}
       - BLOB_STORAGE__SECRET_ACCESS_KEY=${TENZIR_PLATFORM_INTERNAL_SECRET_ACCESS_KEY}
     depends_on:
@@ -55,6 +50,7 @@ services:
 
   websocket-gateway:
     image: ghcr.io/tenzir/platform:${TENZIR_PLATFORM_VERSION:-latest}
+    restart: unless-stopped
     environment:
       - BASE_PATH=
       - TENZIR_PROXY_TIMEOUT=60
@@ -68,6 +64,7 @@ services:
 
   app:
     image: ghcr.io/tenzir/app:${TENZIR_PLATFORM_VERSION:-latest}
+    restart: unless-stopped
     environment:
       AUTH_TRUST_HOST: true
       PUBLIC_ENABLE_HIGHLIGHT: false
@@ -85,10 +82,23 @@ services:
     ports:
       - "3000:3000"
 
+  # For production deployments, we suggest to replace this by an external
+  # postgres instance that is centrally managed and backed up regularly.
+  postgres:
+    image: postgres:14.5
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=${TENZIR_PLATFORM_POSTGRES_USER}
+      - POSTGRES_PASSWORD=${TENZIR_PLATFORM_POSTGRES_PASSWORD}
+      - POSTGRES_DB=${TENZIR_PLATFORM_POSTGRES_DB}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
   # Note the ~25 seconds startup delay before the seaweed server
   # becomes ready.
   seaweed:
     image: ghcr.io/tenzir/tenzir-seaweedfs:${TENZIR_PLATFORM_VERSION:-latest}
+    restart: unless-stopped
     environment:
       - TENZIR_PLATFORM_INTERNAL_ACCESS_KEY_ID
       - TENZIR_PLATFORM_INTERNAL_SECRET_ACCESS_KEY
@@ -112,6 +122,8 @@ services:
       - TENZIR_PLATFORM_CLI_CLIENT_ID=${TENZIR_PLATFORM_CLI_CLIENT_ID}
 
 volumes:
+  postgres_data:
+    driver: local
   seaweed_data:
     driver: local
   cli_cache:

examples/onprem-integrated/env.example

@@ -1,21 +1,26 @@
-# The domain under which the platform frontend is reachable.
+# The domain under which the platform frontend is reachable,
+# eg. `https://app.tenzir.example`
+# Must be routed to the `platform` service by the external HTTPS proxy.
 TENZIR_PLATFORM_DOMAIN=
 
 # The endpoint to which tenzir nodes should connect.
-# Should a url with `ws://` or `wss://` scheme.
+# Should a url with `ws://` or `wss://` scheme, eg. `wss://control.tenzir.example`.
+# Must be routed to the `websocket-gateway` service by the external HTTPS proxy.
 TENZIR_PLATFORM_CONTROL_ENDPOINT=
 
-# The url where the blob storage is exposed.
-TENZIR_PLATFORM_BLOBS_ENDPOINT=
+# The url where the blob storage is exposed, eg. `https://downloads.tenzir.example`.
+# Must be routed to the `seaweed` service by the external HTTPS proxy.
+TENZIR_PLATFORM_DOWNLOADS_ENDPOINT=
 
 # Platform OIDC Policy Configuration
 #  - OIDC_PROVIDER_NAME: A short identifier for the OIDC provider. (e.g. 'auth0', 'keycloak', ...)
 #  - OIDC_PROVIDER_ISSUER_URL: The OIDC provider used for logging into the platform.
 #  - TRUSTED_AUDIENCES: A JSON object containing the OIDC issuer and audiences that should be accepted
 #                       by the platform. Example: '{"issuer": "keycloak.example.org", "audiences": ["tenzir_platform"]}'
-#  - ADMIN_FUNCTIONS: A JSON list of rules granting access to the admin API.
-#                     See the documentation for a description of available rules.
-#                     Example: '[{"connection": "google-oauth2","organization_claim": "tenzir/org","organization": "TenzirPlatformAdmins","auth_fn": "auth_organization"}]'
+#  - ADMIN_FUNCTIONS: A list of rules that determine which users are considered to be an admin by this platform instance.
+#                     See the [documentation](https://docs.tenzir.com/platform-cli#configure-access-rules) for a description
+#                     of available rules, and use the CLI with the `--dry-run` option to conveniently generate them.
+#                     Example: '[{"organization_claim": "tenzir/org", "organization": "TenzirPlatformAdmins", "auth_fn": "auth_organization"}]'
 #                         This example rule grants admin access to all users with a valid signed id_token containing
 #                         the fields `{"connection": "google-oauth2", "tenzir/org": "TenzirPlatformAdmins"}`.
 TENZIR_PLATFORM_OIDC_PROVIDER_NAME=
@@ -34,12 +39,12 @@ TENZIR_PLATFORM_CLI_CLIENT_ID=
 TENZIR_PLATFORM_APP_CLIENT_ID=
 TENZIR_PLATFORM_APP_CLIENT_SECRET=
 
-# Database connection
+# Database connection (pre-configured for the bundled postgres instance)
 TENZIR_PLATFORM_STORE_TYPE=postgres
-TENZIR_PLATFORM_POSTGRES_USER=
-TENZIR_PLATFORM_POSTGRES_PASSWORD=
-TENZIR_PLATFORM_POSTGRES_DB=
-TENZIR_PLATFORM_POSTGRES_HOSTNAME=
+TENZIR_PLATFORM_POSTGRES_USER=postgres
+TENZIR_PLATFORM_POSTGRES_PASSWORD=postgres
+TENZIR_PLATFORM_POSTGRES_DB=platform
+TENZIR_PLATFORM_POSTGRES_HOSTNAME=postgres:5432
 
 
 # -------------------------------------------------------------------------------------------
@@ -52,7 +57,7 @@ TENZIR_PLATFORM_POSTGRES_HOSTNAME=
 #      Generate with `openssl rand -hex 32`.
 #  - TENANT_TOKEN_ENCRYPTION_KEY:
 #      Encryption key used to generate user keys
-#      Generate with `openssl rand 32 | base64encode`.
+#      Generate with `openssl rand 32 | base64`.
 #  - APP_API_KEY:
 #      An arbitrary random string used by the app to access the `/webapp` API.
 #      Generate with `openssl rand -hex 32`.
@@ -61,7 +66,8 @@ TENZIR_PLATFORM_INTERNAL_TENANT_TOKEN_ENCRYPTION_KEY=
 TENZIR_PLATFORM_INTERNAL_APP_API_KEY=
 
 # The access key must be valid and must have read and write permissions on the bucket.
-# When using the bundled seaweed instance, this means they must match the values in `seaweed/config.json`
+# When using the bundled seaweed instance, these are can be chosen arbitrarily as they
+# are automatically written into `/config.json` in the seaweed container.
 TENZIR_PLATFORM_INTERNAL_BUCKET_NAME=platform-bucket
 TENZIR_PLATFORM_INTERNAL_ACCESS_KEY_ID=86ac27778503b3396e934126cea384bc
 TENZIR_PLATFORM_INTERNAL_SECRET_ACCESS_KEY=db973c3a1f67b7024c4a77d2fe41ca63