02 Install with Docker

This chapter covers public deployment of SSH Teams using prebuilt Docker images.

Use one of these modes:

Nitrate mode (default): SSH Teams uses its embedded Nitrate NoSQL database.
External MongoDB mode: SSH Teams connects to your own MongoDB instance using MONGODB_URI.

Important: choose one mode per deployment. Do not configure Nitrate mode and external MongoDB mode at the same time.

2.1 Deployment Options

Choose a deployment mode based on operational ownership.

Mode	Choose this when	Trade-off
Nitrate (embedded)	You want the fastest single-node startup for labs and small deployments	Simpler operations, less external DB control
External MongoDB	You already run MongoDB with backup/HA controls	More moving parts, stronger DB lifecycle control

graph TD
    A[Operator Host] --> B{Deployment Mode}

    B --> C[Nitrate Mode]
    B --> D[External MongoDB Mode]

    C --> E[sshteam container]
    E --> F[conf.d volume]
    E --> G[nitrate data volume]

    D --> H[sshteam container]
    H --> I[conf.d volume]
    H --> J[(External MongoDB)]

    K[Host ports 8080 and 8443] --> E
    K --> H

Nitrate mode

Best for evaluation, development, and small single-node deployments.
Nitrate database files are stored on a mounted host folder (for example ./nitrate/data).
No MONGODB_URI is required.

External MongoDB mode

Best when you already operate MongoDB separately or need independent DB lifecycle management.
Set SSHTEAM_PERSISTENCE_BACKEND=mongo and provide MONGODB_URI.
Application config/cert material remains on mounted conf.d.

2.2 Prerequisites

Requirement	Lab	Staging	Production
Docker Engine and Compose plugin	Required	Required	Required
Pull access to `jadaptive/sshteam:latest`	Required	Required	Required
Host ports available (`8080`, `8443` in examples)	Required	Required	Required
Persistent storage path planning	Recommended	Required	Required
Backup plan for config/data	Optional	Recommended	Required
Trusted TLS certificate plan	Optional	Recommended	Required

Quick preflight checks:

docker --version
docker compose version
docker pull jadaptive/sshteam:latest

2.3 Required Volumes and Ports

Port mapping:
- Host 8080 -> Container 8888 (HTTP)
- Host 8443 -> Container 8443 (HTTPS)
Recommended mounts:
- ./nitrate/conf.d:/app/conf.d for cert/config persistence.
- ./nitrate/data:/app/nitrate/data for Nitrate data files (Nitrate mode only).
External MongoDB mode:
- Keep conf.d mount.
- data mount is optional and typically omitted.

Local data folder conventions

These docs use ./nitrate for local persistence by default.
You can use any folder name (./mongo, ./data, etc.) as long as mount paths are correct.

Example alternate mounts:

-v "$(pwd)/mongo/conf.d:/app/conf.d" \
-v "$(pwd)/mongo/data:/app/nitrate/data"

2.4 Environment Variables and Defaults

Core runtime variables:

HTTP_PORT (default 8888)
HTTPS_PORT (default 8443)
SSHTEAM_PERSISTENCE_BACKEND (nitrate or mongo)
MONGODB_URI (required only for External MongoDB mode)

Legacy compatibility:

SERVER_PORT is still accepted as fallback for HTTP_PORT.
SSHTEAM_HTTPS_PORT is still accepted as fallback for HTTPS_PORT.

Nitrate runtime tuning:

MONGO_WIREDTIGER_CACHE_GB (default 0.25)

Note: for external MongoDB mode, set both SSHTEAM_PERSISTENCE_BACKEND=mongo and MONGODB_URI.

2.5 First Container Startup Validation

After starting the container:

Open https://localhost:8443.
Complete first-time setup (team + admin account).
Log in and verify dashboard access.

Quick health checks:

docker ps --filter name=sshteam
docker logs --tail=100 sshteam

If startup checks fail, jump to 12-troubleshooting-handbook.md#122-install-and-startup-failures.

2.6 Docker Run Examples

Nitrate run command

mkdir -p ./nitrate/conf.d ./nitrate/data

docker run -d \
    --name sshteam \
    -p 8080:8888 \
    -p 8443:8443 \
    -v "$(pwd)/nitrate/conf.d:/app/conf.d" \
    -v "$(pwd)/nitrate/data:/app/nitrate/data" \
    -e SSHTEAM_PERSISTENCE_BACKEND=nitrate \
    -e HTTP_PORT=8888 \
    -e HTTPS_PORT=8443 \
    jadaptive/sshteam:latest

External MongoDB run command

mkdir -p ./nitrate/conf.d

docker run -d \
    --name sshteam \
    -p 8080:8888 \
    -p 8443:8443 \
    -v "$(pwd)/nitrate/conf.d:/app/conf.d" \
    -e SSHTEAM_PERSISTENCE_BACKEND=mongo \
    -e HTTP_PORT=8888 \
    -e HTTPS_PORT=8443 \
    -e MONGODB_URI="mongodb://mongo:27017/sshteam" \
    jadaptive/sshteam:latest

Replace mongodb://mongo:27017/sshteam with your actual MongoDB endpoint/credentials.

2.7 Docker Compose Examples

Nitrate compose file

services:
    sshteam:
        image: jadaptive/sshteam:latest
        container_name: sshteam
        ports:
            - "8080:8888"
            - "8443:8443"
        environment:
            SSHTEAM_PERSISTENCE_BACKEND: "nitrate"
            HTTP_PORT: "8888"
            HTTPS_PORT: "8443"
        volumes:
            - ./nitrate/conf.d:/app/conf.d
            - ./nitrate/data:/app/nitrate/data
        restart: unless-stopped

External MongoDB compose file

services:
    mongo:
        image: mongo:8
        container_name: sshteam-mongo
        volumes:
            - ./mongo/data:/data/db
        restart: unless-stopped

    sshteam:
        image: jadaptive/sshteam:latest
        container_name: sshteam
        depends_on:
            - mongo
        ports:
            - "8080:8888"
            - "8443:8443"
        environment:
            SSHTEAM_PERSISTENCE_BACKEND: "mongo"
            HTTP_PORT: "8888"
            HTTPS_PORT: "8443"
            MONGODB_URI: "mongodb://mongo:27017/sshteam"
        volumes:
            - ./nitrate/conf.d:/app/conf.d
        restart: unless-stopped

Start either compose deployment with:

docker compose up -d

2.8 Upgrade and Rollback Strategy

Upgrade:

Pull updated image tag.
Recreate container with the same volume mounts and environment variables.
Verify login, dashboard, and certificate issuance paths.

Rollback:

Stop the new container.
Start previous known-good image tag with the same mounts/env.
Confirm service health.

Because data/certs are on mounted volumes, container replacement is straightforward.

2.9 Install Troubleshooting

Container starts but UI unavailable:
- Confirm port mapping (8080:8888, 8443:8443) and host firewall rules.
Login/setup redirects unexpectedly:
- Check docker logs sshteam for startup errors.
External MongoDB mode cannot connect:
- Verify MONGODB_URI host, port, credentials, and network reachability.
- If using Compose, ensure SSH Teams and MongoDB are in the same compose project/network.
TLS/certificate issues:
- Ensure /app/conf.d is mounted and writable by Docker.