From 74a005ba7f97db7a246b3a1c9aa07b189422c33a Mon Sep 17 00:00:00 2001 From: Bryan Frimin Date: Fri, 31 Oct 2025 16:01:11 +0100 Subject: [PATCH] Update documentation Signed-off-by: Bryan Frimin --- compose.prod.yaml | 2 +- docs/DOCKER_ENVIRONMENT_VARIABLES.md | 188 +++++++++++++-------------- docs/INSTALLATION.md | 7 +- entrypoint.sh | 2 +- 4 files changed, 98 insertions(+), 101 deletions(-) diff --git a/compose.prod.yaml b/compose.prod.yaml index 6ed2c9cde..e34d25549 100644 --- a/compose.prod.yaml +++ b/compose.prod.yaml @@ -9,7 +9,7 @@ services: TRUST_AUTH_TOKEN_SECRET: "this-is-a-secure-secret-for-trust-token-signing-at-least-32-bytes" # Application settings - PROBOD_HOSTNAME: "localhost:8080" + PROBOD_BASE_URL: "http://localhost:8080" API_ADDR: "localhost:8080" API_CORS_ALLOWED_ORIGINS: "http://localhost:8080" diff --git a/docs/DOCKER_ENVIRONMENT_VARIABLES.md b/docs/DOCKER_ENVIRONMENT_VARIABLES.md index 078cc4b10..fc8d388c8 100644 --- a/docs/DOCKER_ENVIRONMENT_VARIABLES.md +++ b/docs/DOCKER_ENVIRONMENT_VARIABLES.md @@ -4,143 +4,143 @@ This document provides a comprehensive reference for all environment variables u ## Configuration File -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `CONFIG_FILE` | Path to the configuration file | `/etc/probod/config.yml` | No | +| Variable | Description | Default Value | Required | +| ------------- | ------------------------------ | ------------------------ | -------- | +| `CONFIG_FILE` | Path to the configuration file | `/etc/probod/config.yml` | No | ## Observability ### Metrics -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `METRICS_ADDR` | Address for Prometheus metrics endpoint | `localhost:8081` | No | +| Variable | Description | Default Value | Required | +| -------------- | --------------------------------------- | ---------------- | -------- | +| `METRICS_ADDR` | Address for Prometheus metrics endpoint | `localhost:8081` | No | ### Tracing -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `TRACING_ADDR` | OpenTelemetry collector address for distributed tracing | `localhost:4317` | No | -| `TRACING_MAX_BATCH_SIZE` | Maximum number of spans to batch before export | `512` | No | -| `TRACING_BATCH_TIMEOUT` | Timeout in seconds for batching spans | `5` | No | -| `TRACING_EXPORT_TIMEOUT` | Timeout in seconds for exporting traces | `30` | No | -| `TRACING_MAX_QUEUE_SIZE` | Maximum queue size for spans waiting to be exported | `2048` | No | +| Variable | Description | Default Value | Required | +| ------------------------ | ------------------------------------------------------- | ---------------- | -------- | +| `TRACING_ADDR` | OpenTelemetry collector address for distributed tracing | `localhost:4317` | No | +| `TRACING_MAX_BATCH_SIZE` | Maximum number of spans to batch before export | `512` | No | +| `TRACING_BATCH_TIMEOUT` | Timeout in seconds for batching spans | `5` | No | +| `TRACING_EXPORT_TIMEOUT` | Timeout in seconds for exporting traces | `30` | No | +| `TRACING_MAX_QUEUE_SIZE` | Maximum queue size for spans waiting to be exported | `2048` | No | ## Application Configuration -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `PROBOD_HOSTNAME` | Public hostname for the Probo instance (used for URL generation) | `localhost:8080` | No | -| `PROBOD_ENCRYPTION_KEY` | Base64-encoded encryption key for sensitive data (32+ bytes) | - | **Yes** | -| `CHROME_DP_ADDR` | Chrome DevTools Protocol address for PDF generation | `localhost:9222` | No | +| Variable | Description | Default Value | Required | +| ----------------------- | ---------------------------------------------------------------- | ----------------------- | -------- | +| `PROBOD_BASE_URL` | Public hostname for the Probo instance (used for URL generation) | `http://localhost:8080` | No | +| `PROBOD_ENCRYPTION_KEY` | Base64-encoded encryption key for sensitive data (32+ bytes) | - | **Yes** | +| `CHROME_DP_ADDR` | Chrome DevTools Protocol address for PDF generation | `localhost:9222` | No | ## API Configuration -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `API_ADDR` | Address and port for the API server to bind to | `:8080` | No | -| `API_CORS_ALLOWED_ORIGINS` | Comma-separated list of allowed CORS origins | `http://localhost:8080` | No | +| Variable | Description | Default Value | Required | +| -------------------------- | ---------------------------------------------- | ----------------------- | -------- | +| `API_ADDR` | Address and port for the API server to bind to | `:8080` | No | +| `API_CORS_ALLOWED_ORIGINS` | Comma-separated list of allowed CORS origins | `http://localhost:8080` | No | ## PostgreSQL Database -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `PG_ADDR` | PostgreSQL server address and port | `localhost:5432` | No | -| `PG_USERNAME` | PostgreSQL username | `postgres` | No | -| `PG_PASSWORD` | PostgreSQL password | `postgres` | No | -| `PG_DATABASE` | PostgreSQL database name | `probod` | No | -| `PG_POOL_SIZE` | Maximum number of connections in the database pool | `100` | No | +| Variable | Description | Default Value | Required | +| -------------- | -------------------------------------------------- | ---------------- | -------- | +| `PG_ADDR` | PostgreSQL server address and port | `localhost:5432` | No | +| `PG_USERNAME` | PostgreSQL username | `postgres` | No | +| `PG_PASSWORD` | PostgreSQL password | `postgres` | No | +| `PG_DATABASE` | PostgreSQL database name | `probod` | No | +| `PG_POOL_SIZE` | Maximum number of connections in the database pool | `100` | No | ## Authentication ### User Authentication -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `AUTH_DISABLE_SIGNUP` | Disable user self-registration | `false` | No | -| `AUTH_INVITATION_TOKEN_VALIDITY` | Invitation token validity duration in seconds | `3600` (1 hour) | No | +| Variable | Description | Default Value | Required | +| -------------------------------- | --------------------------------------------- | --------------- | -------- | +| `AUTH_DISABLE_SIGNUP` | Disable user self-registration | `false` | No | +| `AUTH_INVITATION_TOKEN_VALIDITY` | Invitation token validity duration in seconds | `3600` (1 hour) | No | ### Authentication Cookies -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `AUTH_COOKIE_NAME` | Name of the session cookie | `SSID` | No | -| `AUTH_COOKIE_DOMAIN` | Domain for the session cookie | `localhost` | No | -| `AUTH_COOKIE_SECRET` | Secret key for signing session cookies (32+ bytes) | - | **Yes** | -| `AUTH_COOKIE_DURATION` | Session cookie validity duration in hours | `24` | No | +| Variable | Description | Default Value | Required | +| ---------------------- | -------------------------------------------------- | ------------- | -------- | +| `AUTH_COOKIE_NAME` | Name of the session cookie | `SSID` | No | +| `AUTH_COOKIE_DOMAIN` | Domain for the session cookie | `localhost` | No | +| `AUTH_COOKIE_SECRET` | Secret key for signing session cookies (32+ bytes) | - | **Yes** | +| `AUTH_COOKIE_DURATION` | Session cookie validity duration in hours | `24` | No | ### Password Security -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `AUTH_PASSWORD_PEPPER` | Secret pepper value for password hashing (32+ bytes) | - | **Yes** | -| `AUTH_PASSWORD_ITERATIONS` | Number of PBKDF2 iterations for password hashing | `1000000` | No | +| Variable | Description | Default Value | Required | +| -------------------------- | ---------------------------------------------------- | ------------- | -------- | +| `AUTH_PASSWORD_PEPPER` | Secret pepper value for password hashing (32+ bytes) | - | **Yes** | +| `AUTH_PASSWORD_ITERATIONS` | Number of PBKDF2 iterations for password hashing | `1000000` | No | ## Trust Center Authentication -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `TRUST_AUTH_COOKIE_NAME` | Name of the trust center token cookie | `TCT` | No | -| `TRUST_AUTH_COOKIE_DOMAIN` | Domain for the trust center cookie | `localhost` | No | -| `TRUST_AUTH_COOKIE_DURATION` | Trust center cookie validity duration in hours | `24` | No | -| `TRUST_AUTH_TOKEN_DURATION` | Trust center access token validity duration in hours | `168` (7 days) | No | -| `TRUST_AUTH_REPORT_URL_DURATION` | Validity duration for report URLs in minutes | `15` | No | -| `TRUST_AUTH_TOKEN_SECRET` | Secret key for signing trust center tokens (32+ bytes) | - | **Yes** | -| `TRUST_AUTH_SCOPE` | OAuth2 scope for trust center access | `trust_center_readonly` | No | -| `TRUST_AUTH_TOKEN_TYPE` | Token type identifier for trust center tokens | `trust_center_access` | No | +| Variable | Description | Default Value | Required | +| -------------------------------- | ------------------------------------------------------ | ----------------------- | -------- | +| `TRUST_AUTH_COOKIE_NAME` | Name of the trust center token cookie | `TCT` | No | +| `TRUST_AUTH_COOKIE_DOMAIN` | Domain for the trust center cookie | `localhost` | No | +| `TRUST_AUTH_COOKIE_DURATION` | Trust center cookie validity duration in hours | `24` | No | +| `TRUST_AUTH_TOKEN_DURATION` | Trust center access token validity duration in hours | `168` (7 days) | No | +| `TRUST_AUTH_REPORT_URL_DURATION` | Validity duration for report URLs in minutes | `15` | No | +| `TRUST_AUTH_TOKEN_SECRET` | Secret key for signing trust center tokens (32+ bytes) | - | **Yes** | +| `TRUST_AUTH_SCOPE` | OAuth2 scope for trust center access | `trust_center_readonly` | No | +| `TRUST_AUTH_TOKEN_TYPE` | Token type identifier for trust center tokens | `trust_center_access` | No | ## AWS / S3 Storage -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `AWS_REGION` | AWS region for S3 storage | `us-east-1` | No | -| `AWS_BUCKET` | S3 bucket name for file storage | `probod` | No | -| `AWS_ACCESS_KEY_ID` | AWS access key ID (leave empty for IAM role) | - | No | -| `AWS_SECRET_ACCESS_KEY` | AWS secret access key (leave empty for IAM role) | - | No | -| `AWS_ENDPOINT` | Custom S3 endpoint (for MinIO or S3-compatible services) | - | No | +| Variable | Description | Default Value | Required | +| ----------------------- | -------------------------------------------------------- | ------------- | -------- | +| `AWS_REGION` | AWS region for S3 storage | `us-east-1` | No | +| `AWS_BUCKET` | S3 bucket name for file storage | `probod` | No | +| `AWS_ACCESS_KEY_ID` | AWS access key ID (leave empty for IAM role) | - | No | +| `AWS_SECRET_ACCESS_KEY` | AWS secret access key (leave empty for IAM role) | - | No | +| `AWS_ENDPOINT` | Custom S3 endpoint (for MinIO or S3-compatible services) | - | No | ## Notifications ### Email (SMTP) -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `MAILER_SENDER_NAME` | Display name for outgoing emails | `Probo` | No | -| `MAILER_SENDER_EMAIL` | Email address for outgoing emails | `no-reply@notification.getprobo.com` | No | -| `SMTP_ADDR` | SMTP server address and port | `localhost:1025` | No | -| `SMTP_TLS_REQUIRED` | Require TLS for SMTP connections | `false` | No | -| `MAILER_INTERVAL` | Interval in seconds for processing email queue | `60` | No | +| Variable | Description | Default Value | Required | +| --------------------- | ---------------------------------------------- | ------------------------------------ | -------- | +| `MAILER_SENDER_NAME` | Display name for outgoing emails | `Probo` | No | +| `MAILER_SENDER_EMAIL` | Email address for outgoing emails | `no-reply@notification.getprobo.com` | No | +| `SMTP_ADDR` | SMTP server address and port | `localhost:1025` | No | +| `SMTP_TLS_REQUIRED` | Require TLS for SMTP connections | `false` | No | +| `MAILER_INTERVAL` | Interval in seconds for processing email queue | `60` | No | ### Slack -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `SLACK_SENDER_INTERVAL` | Interval in seconds for processing Slack notification queue | `60` | No | +| Variable | Description | Default Value | Required | +| ----------------------- | ----------------------------------------------------------- | ------------- | -------- | +| `SLACK_SENDER_INTERVAL` | Interval in seconds for processing Slack notification queue | `60` | No | ## OpenAI Integration -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `OPENAI_API_KEY` | OpenAI API key for AI-powered features | - | No | -| `OPENAI_TEMPERATURE` | Temperature parameter for OpenAI completions (0.0-2.0) | `0.1` | No | -| `OPENAI_MODEL_NAME` | OpenAI model name to use | `gpt-4o` | No | +| Variable | Description | Default Value | Required | +| -------------------- | ------------------------------------------------------ | ------------- | -------- | +| `OPENAI_API_KEY` | OpenAI API key for AI-powered features | - | No | +| `OPENAI_TEMPERATURE` | Temperature parameter for OpenAI completions (0.0-2.0) | `0.1` | No | +| `OPENAI_MODEL_NAME` | OpenAI model name to use | `gpt-4o` | No | ## Custom Domains -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `CUSTOM_DOMAINS_RENEWAL_INTERVAL` | Interval in seconds for checking certificate renewals | `3600` (1 hour) | No | -| `CUSTOM_DOMAINS_PROVISION_INTERVAL` | Interval in seconds for provisioning new domains | `30` | No | -| `CUSTOM_DOMAINS_CNAME_TARGET` | CNAME target for custom domains | `custom.getprobo.com` | No | +| Variable | Description | Default Value | Required | +| ----------------------------------- | ----------------------------------------------------- | --------------------- | -------- | +| `CUSTOM_DOMAINS_RENEWAL_INTERVAL` | Interval in seconds for checking certificate renewals | `3600` (1 hour) | No | +| `CUSTOM_DOMAINS_PROVISION_INTERVAL` | Interval in seconds for provisioning new domains | `30` | No | +| `CUSTOM_DOMAINS_CNAME_TARGET` | CNAME target for custom domains | `custom.getprobo.com` | No | ### ACME / Let's Encrypt -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `ACME_DIRECTORY` | ACME directory URL for certificate issuance | `https://acme-v02.api.letsencrypt.org/directory` | No | -| `ACME_EMAIL` | Email address for ACME account registration | `admin@getprobo.com` | No | -| `ACME_KEY_TYPE` | Key type for ACME certificates (RSA2048, RSA4096, EC256, EC384) | `EC256` | No | -| `ACME_ROOT_CA` | Custom root CA certificate (PEM format) | - | No | +| Variable | Description | Default Value | Required | +| ---------------- | --------------------------------------------------------------- | ------------------------------------------------ | -------- | +| `ACME_DIRECTORY` | ACME directory URL for certificate issuance | `https://acme-v02.api.letsencrypt.org/directory` | No | +| `ACME_EMAIL` | Email address for ACME account registration | `admin@getprobo.com` | No | +| `ACME_KEY_TYPE` | Key type for ACME certificates (RSA2048, RSA4096, EC256, EC384) | `EC256` | No | +| `ACME_ROOT_CA` | Custom root CA certificate (PEM format) | - | No | ## Connectors @@ -148,14 +148,14 @@ This document provides a comprehensive reference for all environment variables u These variables are only used if `CONNECTOR_SLACK_CLIENT_ID` is set. -| Variable | Description | Default Value | Required | -|----------|-------------|---------------|----------| -| `CONNECTOR_SLACK_CLIENT_ID` | Slack OAuth2 app client ID | - | No | -| `CONNECTOR_SLACK_CLIENT_SECRET` | Slack OAuth2 app client secret | - | **Yes** (if client ID set) | -| `CONNECTOR_SLACK_REDIRECT_URI` | OAuth2 redirect URI for Slack connector | `https://localhost:8080/api/console/v1/connectors/complete` | No | -| `CONNECTOR_SLACK_AUTH_URL` | Slack OAuth2 authorization endpoint | `https://slack.com/oauth/v2/authorize` | No | -| `CONNECTOR_SLACK_TOKEN_URL` | Slack OAuth2 token endpoint | `https://slack.com/api/oauth.v2.access` | No | -| `CONNECTOR_SLACK_SIGNING_SECRET` | Slack app signing secret for webhook verification | - | **Yes** (if client ID set) | +| Variable | Description | Default Value | Required | +| -------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- | -------------------------- | +| `CONNECTOR_SLACK_CLIENT_ID` | Slack OAuth2 app client ID | - | No | +| `CONNECTOR_SLACK_CLIENT_SECRET` | Slack OAuth2 app client secret | - | **Yes** (if client ID set) | +| `CONNECTOR_SLACK_REDIRECT_URI` | OAuth2 redirect URI for Slack connector | `https://localhost:8080/api/console/v1/connectors/complete` | No | +| `CONNECTOR_SLACK_AUTH_URL` | Slack OAuth2 authorization endpoint | `https://slack.com/oauth/v2/authorize` | No | +| `CONNECTOR_SLACK_TOKEN_URL` | Slack OAuth2 token endpoint | `https://slack.com/api/oauth.v2.access` | No | +| `CONNECTOR_SLACK_SIGNING_SECRET` | Slack app signing secret for webhook verification | - | **Yes** (if client ID set) | ## Security Best Practices diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index dd3607548..0b0acb789 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -48,7 +48,7 @@ services: TRUST_AUTH_TOKEN_SECRET: "this-is-a-secure-secret-for-trust-token-signing-at-least-32-bytes" # Application settings - PROBOD_HOSTNAME: "localhost:8080" + PROBOD_BASE_URL: "http://localhost:8080" API_ADDR: "localhost:8080" API_CORS_ALLOWED_ORIGINS: "http://localhost:8080" @@ -89,7 +89,6 @@ services: - minio - chrome - postgres: image: "postgres:17.4" shm_size: "1g" @@ -136,12 +135,12 @@ services: - "--disable-background-timer-throttling" - "--disable-extensions" - volumes: probo-data: postgres-data: minio-data: ``` + #### With mounted Config File You can find an example configuration file [here](../cfg/dev.yaml) and modify it as needed. @@ -164,7 +163,6 @@ services: - minio - chrome - postgres: image: "postgres:17.4" shm_size: "1g" @@ -211,7 +209,6 @@ services: - "--disable-background-timer-throttling" - "--disable-extensions" - volumes: probo-data: postgres-data: diff --git a/entrypoint.sh b/entrypoint.sh index 0f60842e1..6f8ba49f3 100644 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -25,7 +25,7 @@ unit: max-queue-size: ${TRACING_MAX_QUEUE_SIZE:-2048} probod: - hostname: "${PROBOD_HOSTNAME:-localhost:8080}" + base-url: "${PROBOD_BASE_URL:-http://localhost:8080}" encryption-key: "${PROBOD_ENCRYPTION_KEY:?PROBOD_ENCRYPTION_KEY is required}" chrome-dp-addr: "${CHROME_DP_ADDR:-localhost:9222}"