Developer Docker
The developer Docker bundle builds SSL Teams from source and runs the result in a local Compose stack. This guide covers source builds and local Compose operations for Java, React, and Docker development. For deployments using the published image, see Deploy With Docker. That guide also defines JWT signing-key ownership, host and container paths, persistence, backup, and rotation.
Prerequisites
Install and make sure these commands are available on your PATH:
- Docker with Docker Compose support
- OpenSSL
- curl
- Maven
- pnpm
The build uses the repository's Maven POMs and pnpm lock file. It does not pull or use the published SSL Teams application image.
Start the local stack
From the repository root:
cd sslteam-services/docker/local-dev
cp .env.example .env
./local.sh all
The all command performs these steps:
- Creates the local
.envfile when it is missing and generates local passwords and the JWT issuer. - Generates a local JWT signing key on the host in
docker/local-dev/.docker-secrets/when one is missing. The directory is excluded from Git tracking, so the private key remains on the development host and is not added to source control. - Installs the locked web dependencies with pnpm.
- Packages the Quarkus application with Maven.
- Builds the
localhost/sslteam-app:localDocker image. - Validates the Compose configuration and starts PostgreSQL and SSL Teams.
The local service is available at:
https://localhost:15080/
Local Docker profile and developer UIs
The local Docker bundle builds the application from source, but it starts the
packaged image with the prod Quarkus profile. It is therefore not Quarkus
Dev Mode and does not expose the Quarkus Dev UI at /q/dev-ui.
The local bundle applies the production endpoint policy as well:
| Surface | Local Docker behavior |
|---|---|
| SSL Teams dashboard and API | Available on https://localhost:15080/ |
| Quarkus health checks | Available at http://127.0.0.1:9000/q/health/ready; Compose binds management port 9000 to host loopback only |
| OpenAPI | Disabled by the packaged image's prod profile |
| Swagger UI | Available only when the application is run in Quarkus dev or test mode; not enabled by the local Docker image's prod profile |
| Health UI | Available only when included by the active Quarkus profile; disabled explicitly in prod |
| Quarkus Dev UI | Available only in Quarkus Dev Mode, never in this Docker image |
The local Docker bundle therefore has two local-only ports: 15080 for the
dashboard/API and 9000 for management health. Port 9000 is not exposed to
the LAN or internet.
In true Quarkus dev or test mode, the project explicitly enables OpenAPI,
Swagger UI, and Health UI. Quarkus Dev UI is available only in actual Quarkus
Dev Mode; it is not a test-profile endpoint. Start the application with the
repository's Quarkus Dev Mode or test workflow rather than ./local.sh when
those surfaces are required. Do not expose them through a shared or
production-facing network. The local Docker bundle is intended for packaged
application and dashboard testing, not for testing Quarkus build-time developer
tooling.
The local bundle uses the host-managed JWT mode described in Deploy With Docker. Compose mounts the host file into the application as /run/secrets/jwt-private-b64; the application uses that mounted path, not the host path. The key is reused across local restarts so existing local tokens remain verifiable.
The local key file is created by ./local.sh seed or ./local.sh all at
docker/local-dev/.docker-secrets/jwt-ed25519-private-pkcs8.b64. Manual key
creation is normally unnecessary. If a provisioning workflow must create it
first, use the same Ed25519 OpenSSL procedure documented in Deploy With
Docker, using the
docker/local-dev directory as the working directory. Keep the file local and
do not copy it into a production deployment.
The HTTPS endpoint uses a startup TLS certificate generated inside the persistent
server-state volume. This is transport trust for the SSL Teams service; it is
not the application Root CA used to sign demo leaf certificates. Configure the
CLI's origin-scoped transport trust before running authenticated CLI commands:
sslteam tls tofu --origin https://localhost:15080
sslteam tls tofu \
--origin https://localhost:15080 \
--fingerprint <verified-sha256-fingerprint>
Discover and approve the fingerprint only after checking it through an
independent local-development channel. Do not install the application Root CA
to trust this endpoint, and do not use curl -k as a substitute for transport
verification.
The local key is for development only and must not be copied into a production deployment. Production deployments use the JWT ownership and protection model documented in Deploy With Docker.
Run individual steps
Individual workflow steps are available through the following commands:
./local.sh seed # Create .env and the local JWT key
./local.sh build # Build the application and local image
./local.sh start # Start the existing local image
./local.sh status # Show local service status
./local.sh logs # Follow application logs
./local.sh stop # Stop containers and retain local volumes
./local.sh reset # Stop containers and delete local volumes
start does not build a new image. Run build first after changing source code.
Local isolation and reset
The developer bundle uses the separate Compose project sslteam-local, the image localhost/sslteam-app:local, and local development volumes. This keeps its containers and volumes separate from the production project.
Both bundles use port 15080. Stop the other stack before starting the developer stack if the port is already in use.
reset deletes the local PostgreSQL and application-state volumes. This removes local users, certificates, and other application state. The host-side JWT key is retained for the next local start because it is stored outside those Compose volumes. Its directory is excluded from Git tracking.
The developer bundle is not a production deployment path: it builds with -DskipTests, uses generated local credentials, and keeps development state on the local machine.