# Container Environment

The official container image uses `probod-bootstrap` to convert `PROBOD_*`
environment variables into a YAML configuration file before starting `probod`.

  Environment variables are an input to `probod-bootstrap`, not to the
  application process. When running `probod` directly, pass a [JSON or YAML
  file](/docs/deployment/configuration/config-file) with `-cfg-file`.

## Startup behavior

`CONFIG_FILE` selects the generated or mounted configuration file and defaults
to `/etc/probod/config.yml`.

On every container start:

1. When `PROBOD_ENCRYPTION_KEY` is set, the entrypoint generates
   `CONFIG_FILE` from the environment. Existing file content is replaced.
2. Otherwise, the entrypoint uses the existing `CONFIG_FILE`.
3. Startup fails when neither source is available.

This makes `PROBOD_ENCRYPTION_KEY` the switch between environment-generated and
directly managed configuration.

## Required inputs

`probod-bootstrap` requires four persistent secrets:

| Variable                           | Purpose                                           |
| ---------------------------------- | ------------------------------------------------- |
| `PROBOD_ENCRYPTION_KEY`            | Encrypts sensitive application data at rest       |
| `PROBOD_AUTH_COOKIE_SECRET`        | Signs session cookies                             |
| `PROBOD_AUTH_PASSWORD_PEPPER`      | Adds a deployment secret to password hashing      |
| `PROBOD_OAUTH2_SERVER_SIGNING_KEY` | PEM RSA private key used to sign OAuth 2.0 tokens |

Generate separate random values for the first three settings and an RSA key for
the signing key:

```bash
openssl rand -base64 32
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048
```

Set these values before the first production start, keep them stable across
restarts and application instances, and include them in recovery procedures.

  Replacing `PROBOD_ENCRYPTION_KEY` does not re-encrypt existing records. Use an
  application-supported migration procedure when one is available.

## Configure the application

Set infrastructure and application values alongside the required secrets. This
minimal example shows the main inputs; it is not a complete variable list.

```bash
PROBOD_BASE_URL=https://probo.example.com
PROBOD_API_ADDR=0.0.0.0:8080
PROBOD_API_CORS_ALLOWED_ORIGINS=https://probo.example.com

PROBOD_PG_ADDR=postgres.example.com:5432
PROBOD_PG_USERNAME=probod
PROBOD_PG_PASSWORD=replace-me
PROBOD_PG_DATABASE=probod

PROBOD_AWS_REGION=eu-west-1
PROBOD_AWS_BUCKET=probo-production
```

The bootstrap process applies documented defaults, converts strings to the
required types, and fails before writing the file when a required value is
missing or a value cannot be parsed.

## Compliance Portal TLS

Compliance Portals listen separately from the console and API because they
route requests by the visitor-facing domain. Choose the mode that matches the
network path for those portal requests:

| Variable value | TLS endpoint | Portal listener |
| -------------- | ------------ | --------------- |
| `PROBOD_TRUST_CENTER_TLS_MODE=direct` | Probo | `PROBOD_TRUST_CENTER_HTTP_ADDR` for HTTP and `PROBOD_TRUST_CENTER_HTTPS_ADDR` for HTTPS |
| `PROBOD_TRUST_CENTER_TLS_MODE=external` | Trusted layer-7 proxy | `PROBOD_TRUST_CENTER_HTTP_ADDR` for forwarded HTTP requests |

`direct` is the default. It requires TCP passthrough so Probo receives TLS SNI
and can select the certificate for the requested portal domain.

Use `external` when a reverse proxy, ingress controller, tunnel, or hosting
platform terminates TLS. The proxy must:

- forward portal traffic to `PROBOD_TRUST_CENTER_HTTP_ADDR`, not
  `PROBOD_API_ADDR`;
- preserve the original `Host` header, or overwrite `X-Forwarded-Host` with the
  original host;
- overwrite `X-Forwarded-Proto` with one `http` or `https` value instead of
  appending to a client-provided value;
- prevent direct public access to the portal HTTP listener; and
- route HTTP ACME challenges under `/.well-known/acme-challenge/` to the same
  listener.

  In external mode, Probo uses the forwarded protocol and host to select a
  Compliance Portal and construct redirects. Do not enable this mode on a
  listener that untrusted clients can reach without passing through a proxy
  that replaces those headers.

`PROBOD_TRUST_CENTER_PROXY_PROTOCOL_TRUSTED_PROXIES` enables the PROXY protocol
when the upstream proxy sends it. List only the proxy source addresses or CIDR
ranges. This setting does not replace network isolation or forwarded-header
sanitization.

For custom domains, also replace the Probo Cloud default in
`PROBOD_CUSTOM_DOMAINS_CNAME_TARGET` with a stable hostname that routes to this
portal entry point. The value is displayed to portal administrators and used
for DNS validation. See [Branding and domains](/docs/product/compliance-portal/branding-and-domains#self-hosted-domains).

## Special input behavior

- `PROBOD_PG_CA_BUNDLE_PATH` reads a PostgreSQL CA bundle from a file and takes
  precedence over the inline `PROBOD_PG_CA_BUNDLE`.
- When both `PROBOD_SAML_CERTIFICATE` and `PROBOD_SAML_PRIVATE_KEY` are absent,
  bootstrap generates a pair. Configure a stable pair when SAML sessions must
  survive container replacement.
- Setting a connector client ID enables that connector and makes its client
  secret required. Slack also requires its signing secret; Vercel also requires
  its integration slug.
- Comma-separated inputs are trimmed and converted to lists.
- Boolean values use `true` or `false`. Numeric durations are expressed in the
  unit stated in the [complete
  reference](/docs/deployment/configuration/environment-reference).
- PEM values must preserve their line breaks.

## External secret references

Every value read by `probod-bootstrap` can be a literal or an AWS secret
reference:

| Syntax                     | Service                             |
| -------------------------- | ----------------------------------- |
| `awssm://<secret-id>`      | AWS Secrets Manager                 |
| `aws://<secret-id>`        | AWS Secrets Manager alias           |
| `awsps://<parameter-name>` | AWS Systems Manager Parameter Store |

```bash
PROBOD_ENCRYPTION_KEY=awssm://probo/production/encryption-key
PROBOD_AUTH_COOKIE_SECRET=awsps:///probo/production/cookie-secret
```

Secret resolution uses the standard AWS SDK credential and region chain.
`PROBOD_AWS_*` configures Probo object storage; it does not authenticate secret
resolution.

## Apply changes

The generated file is a startup artifact, and `probod` does not hot-reload it.
After changing an environment variable or referenced secret, restart every
application instance and confirm that each instance starts successfully.

## Reference

- [Environment variable reference](/docs/deployment/configuration/environment-reference) — Browse every supported PROBOD_* variable, type, default, and requirement