Skip to content

Deploy SSL Teams with Docker

SSL Teams can run from the published Docker image with PostgreSQL supplied by the same Compose stack. This guide is for operators and security teams. It does not cover building the application or publishing images.

This guide is the reference for JWT signing-key configuration in production and developer Docker deployments. The Developer Docker page covers source builds and local Compose commands. JWT key ownership, host and container paths, persistence, backup, and rotation are defined in this guide.

Protect deployment secrets

The deployment environment contains database credentials, bootstrap administrator credentials, and JWT configuration. Keep it private, restrict access to the deployment directory, and include the database and application state in your backup and recovery plan.

Prerequisites

  • Docker with Docker Compose support
  • A host with persistent storage
  • Network access to the published SSL Teams image
  • A hostname whose certificate identities match the names clients will use
  • A decision about who owns the JWT private key

PostgreSQL is included in the deployment stack. It does not need to be installed separately.

JWT key ownership and setup

SSL Teams has two JWT signing-key ownership modes. The mode decides where the private key lives and which component creates it. Choose one before the first start and keep the same signing key for the lifetime of the deployment.

Mode Key owner Where the private key is kept Who creates a missing key? Best fit
host (default) Deployment host and its operators .docker-secrets/ on the host, mounted as a Docker secret deploy.sh before the application starts Production and controlled deployments
container The application container /var/lib/sslteam/jwt/ in the server-state volume The application during startup Simpler self-contained deployments

These are ownership modes, not merely alternate file paths. Complete the section for the selected mode before running ./deploy.sh up.

Host-managed key (default)

The default host-mode settings are:

SSLTEAM_JWT_KEY_MODE=host
SSLTEAM_JWT_PRIVATE_KEY_FILE=./.docker-secrets/jwt-ed25519-private-pkcs8.b64

The deployment script gives exported shell variables precedence over .env. To use the values from .env exactly, clear any previous overrides before starting the deployment:

unset SSLTEAM_JWT_KEY_MODE SSLTEAM_JWT_PRIVATE_KEY_FILE

Host-mode key setup options

Choose one of these options. Do not use more than one option for the same deployment.

Option A: allow the deployment script to create the key. This is the recommended option for a new deployment. When ./deploy.sh up runs, it creates the following file if it is missing:

sslteam-services/docker/production/.docker-secrets/jwt-ed25519-private-pkcs8.b64

The script creates the directory with permission 700, creates the private key file with permission 600, validates the Ed25519 key, and mounts it read-only into the application container. No manual key-generation command is required.

Option B: create the default file with OpenSSL. Use this option when a provisioning process must create the key before deploy.sh runs. Execute the following commands from docker/production:

umask 077
mkdir -p .docker-secrets
openssl genpkey -algorithm Ed25519 -outform DER \
    | openssl base64 -A > .docker-secrets/jwt-ed25519-private-pkcs8.b64
chmod 700 .docker-secrets
chmod 600 .docker-secrets/jwt-ed25519-private-pkcs8.b64

The resulting file must remain at .docker-secrets/jwt-ed25519-private-pkcs8.b64 unless SSLTEAM_JWT_PRIVATE_KEY_FILE is changed to another existing path. Run ./deploy.sh up after creating the file; the deployment validates it before starting the containers.

Option C: supply an existing key file. Copy an existing Base64-encoded PKCS#8 DER Ed25519 private key into a protected location, or reference its existing absolute path in .env:

SSLTEAM_JWT_KEY_MODE=host
SSLTEAM_JWT_PRIVATE_KEY_FILE=/protected/sslteam/jwt-ed25519-private-pkcs8.b64

The file must exist before ./deploy.sh up runs. The deployment validates the file and fails if it is missing, malformed, or not an Ed25519 private key.

Option D: provide key material through the deployment environment. This is an advanced provisioning option using SSLTEAM_AUTH_JWT_ED25519_PRIVATE_KEY_PKCS8_BASE64. The deployment writes the supplied value into the host-managed key file before mounting it. Do not place private key material in .env, source control, shell history, logs, or ordinary build artifacts.

Host and container paths

Docker uses two path namespaces. A path such as ./.docker-secrets/jwt-ed25519-private-pkcs8.b64 is a file on the deployment host. In host mode, Compose mounts that file read-only inside the application container as:

/run/secrets/jwt-private-b64

The application reads the mounted container path. Do not put /run/secrets/jwt-private-b64 in SSLTEAM_JWT_PRIVATE_KEY_FILE; that setting identifies the host-side source file used by Compose.

The developer bundle uses the same host-managed mapping with its local source file at docker/local-dev/.docker-secrets/jwt-ed25519-private-pkcs8.b64. Its local script creates the file when it is missing, and Compose mounts it at /run/secrets/jwt-private-b64.

Protect the host key

The .docker-secrets directory contains private signing material. Restrict its permissions, exclude it from source control, and protect it with the same care as the application state and database backups.

Container-managed key

Set the following value in .env:

SSLTEAM_JWT_KEY_MODE=container

Do not create a host-side JWT key file for this mode. Run the deployment normally:

./deploy.sh up

In this mode:

  1. The host-side Docker secret is not mounted.
  2. The application creates the key at /var/lib/sslteam/jwt/jwt-ed25519-private-pkcs8.b64 when it is absent.
  3. The key is persisted in the server-state volume and reused on later starts.
  4. The server-state volume becomes part of the signing-key backup and recovery boundary.

Container mode changes the security boundary

Protect, back up, restore, and restrict access to server-state as sensitive signing-key material. Do not switch between host and container modes after tokens have been issued without an approved migration and key-recovery plan. Changing modes changes the key custody boundary and can prevent verification of existing tokens.

Host mode remains the default because it gives security teams the clearest independent control of the signing key.

JWT bootstrap policy

The deployment bundles keep JWT bootstrap enabled and preserve existing key material. Do not change the internal bootstrap policy during a normal deployment. Choose host or container JWT ownership instead and let deploy.sh configure the corresponding key source.

Changing the bootstrap policy is a recovery or key-rotation operation, not a regular application setting. Disabling bootstrap can leave a fresh deployment without the key files required for authentication. Allowing replacement can change the signing key and invalidate existing tokens while the HTTPS service itself still appears to be running. Use the internal configuration reference and an approved recovery plan before changing it.

First deployment

Complete these steps in order after selecting the JWT ownership mode above.

1. Create the environment file

From a checkout of the sslteam-services repository:

cd sslteam-services/docker/production
cp .env.example .env

2. Configure deployment values

Apply the selected JWT settings from the section above, then edit .env and replace the required values:

POSTGRES_PASSWORD
SSLTEAM_BOOTSTRAP_ADMIN_USERNAME
SSLTEAM_BOOTSTRAP_ADMIN_EMAIL
SSLTEAM_BOOTSTRAP_ADMIN_PASSWORD
SSLTEAM_AUTH_JWT_ISSUER

Set SSLTEAM_CERT_STARTUP_TLS_IDENTITIES to a comma-separated list of DNS names or IPv4 addresses clients will use. The deployment always includes localhost and 127.0.0.1 for local health and management access. Keep .env private. Do not add the JWT private key to .env.

3. Start the deployment

./deploy.sh up

The script creates missing local passwords, generates or validates the JWT key, pulls the published image when needed, starts the stack, and waits for the loopback-only management readiness endpoint. It never runs Maven, pnpm, or docker build.

The default image is jadaptive/sslteam:continuous. For a controlled release, set SSL_TEAM_IMAGE to the approved published tag in .env.

If the command reports SSLTEAM_JWT_PRIVATE_KEY_FILE points to a missing file, the .env file contains a custom host-mode path that does not exist. Restore the default generated-key settings in .env:

SSLTEAM_JWT_KEY_MODE=host
SSLTEAM_JWT_PRIVATE_KEY_FILE=./.docker-secrets/jwt-ed25519-private-pkcs8.b64

Run ./deploy.sh up again. The script creates the missing default key and validates it before starting the containers.

4. Verify the service

The deployment exposes HTTPS on port 15080:

https://localhost:15080/

The startup certificate must be trusted by the client. Do not disable certificate validation or hostname verification to bypass a certificate mismatch.

The Quarkus management interface listens on port 9000, but Compose binds it to 127.0.0.1 on the deployment host. The deployment script uses the readiness endpoint there:

curl --fail --silent --show-error \
    http://127.0.0.1:9000/q/health/ready

Do not publish port 9000 through an internet-facing firewall or reverse proxy. If an external monitoring system needs readiness data, allow only its approved monitoring network to reach this endpoint.

The production image does not expose /q/openapi or Swagger UI. Use the versioned API documentation or the generated OpenAPI build artifact for integration work instead of making an API schema endpoint public.

Application Root CA trust

The application Root CA is the trust anchor for the Intermediate and leaf certificates issued by SSL Teams. It is separate from the startup TLS certificate used by the SSL Teams dashboard and API. Install the public Root only on controlled client systems, after independently verifying its SHA-256 fingerprint. Never install the Root private key or an encrypted Root backup.

After the application CA has been configured, download and install the public Root with the SSL Teams CLI:

# Choose where to store the public Root certificate.
PUBLIC_DIR=/protected/sslteam-public

# Download the public application Root certificate.
sslteam ca root download certificate --out-dir "$PUBLIC_DIR"

# Display the SHA-256 fingerprint for independent approval.
openssl x509 \
    -in "$PUBLIC_DIR/application-root-ca.pem" \
    -noout -subject -issuer -fingerprint -sha256

# Install the approved Root into the native trust store.
sslteam ca trust install \
    --certificate "$PUBLIC_DIR/application-root-ca.pem" \
    --confirm-fingerprint <approved-sha256-fingerprint>

# Confirm that the exact Root is installed.
sslteam ca trust verify \
    --certificate "$PUBLIC_DIR/application-root-ca.pem" \
    --confirm-fingerprint <approved-sha256-fingerprint>

openssl x509 is an optional OpenSSL command that only displays certificate metadata, such as the subject and SHA-256 fingerprint. It does not install the Root or configure an application. Use it when you need to inspect and approve the certificate independently before running sslteam ca trust install.

The default target detects the native macOS, Linux, or Windows trust store; add --java when Java cacerts is also required. Firefox uses a separate profile and requires --target firefox --profile <path> plus Mozilla NSS certutil. For full OS-specific commands, prerequisites, removal, and Firefox details, follow Download and install the public Root certificate, Platform trust details, and CLI Quick Reference.

The trust installation is only the client-side half. Next, create a leaf certificate with the required DNS or IP SAN, deploy the leaf and its Intermediate chain into your HTTPS service, and keep the leaf private key with that service. Follow the Spring Boot 4 HTTPS demo or Quarkus 3.33 HTTPS demo for complete examples.

Once an application is serving that SSL Teams-issued leaf, a client using the native trust store can make a normal HTTPS request:

curl https://localhost:5000

Replace the example port with the port used by your application. Chrome and Safari use the native operating-system trust store; restart them after Root installation and open the same application URL. Firefox must be configured in the intended profile separately. The service must present the leaf and Intermediate chain, and the URL hostname or IP must match the leaf SAN. Do not use curl -k or accept an untrusted browser warning as a substitute for a correct Root, chain, and certificate identity.

Production profile and developer UI policy

The production Compose service sets QUARKUS_PROFILE=prod. The published image therefore does not expose Quarkus Dev UI at /q/dev-ui, Swagger UI, or Health UI. These are developer/test surfaces and must not be enabled or published through a production ingress.

Surface Production policy
SSL Teams dashboard and API Public application surface on HTTPS port 15080, protected by the service authentication and authorization model
/q/health, /q/health/ready, /q/health/live Operator/monitoring surface on management port 9000, bound to host loopback by the Compose bundle
/q/openapi Disabled in the production profile
Swagger UI Disabled in the production profile; never publish it through the application ingress
Health UI Disabled in the production profile
/q/dev-ui Not available in the production profile

Do not change QUARKUS_PROFILE to dev or enable quarkus.swagger-ui.always-include or a production Health UI setting in a shared deployment. If a temporary diagnostic deployment requires one of these surfaces, isolate it from public traffic, use non-production credentials and data, and remove it after use.

Lifecycle commands

Run these from sslteam-services/docker/production:

./deploy.sh status
./deploy.sh logs
./deploy.sh stop
./deploy.sh down

stop stops containers. down removes containers and the network but retains the named PostgreSQL and application-state volumes. Do not remove those volumes during routine maintenance.

To refresh an already cached image:

SSLTEAM_PULL_ALWAYS=true ./deploy.sh up

Upgrades and backups

Back up PostgreSQL and server-state according to the deployment recovery plan. In container-managed JWT mode, server-state contains the private signing key. In host-managed mode, back up .docker-secrets separately and restrict access.

Before an upgrade, verify the selected image tag, database migration behavior, HTTPS health, dashboard access, JWT issuer and audience, and certificate trust. Retain the signing key that existing clients and persisted state require.