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:
- The host-side Docker secret is not mounted.
- The application creates the key at
/var/lib/sslteam/jwt/jwt-ed25519-private-pkcs8.b64when it is absent. - The key is persisted in the
server-statevolume and reused on later starts. - The
server-statevolume 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.