Skip to content

Install with Docker

This guide shows you how to install SSH Teams using Docker. You can choose the built-in database for quick starts, or connect it to your own MongoDB database.

Pick One Database Mode

Do not use the built-in database and external MongoDB at the same time. Choose one and stick with it.

Choose Your Database Mode

Mode Best for Notes
Built-in Nitrate database Trying things out, small teams, or single-server setups Easiest to get started
External MongoDB Teams that already run MongoDB or need backups and failover More setup, but more control

Built-in Database Mode

This is the fastest way to get started. Your data is stored in a folder on the host machine, such as ./nitrate/data.

You do not need to set up MongoDB.

External MongoDB Mode

Use this if you already have MongoDB running or want to manage the database separately.

Set SSHTEAM_PERSISTENCE_BACKEND=mongo and provide a MONGODB_URI pointing to your database.

Before You Start

Make sure you have:

  • Docker installed and running.
  • Ports 8080 and 8443 available on your host machine.
  • A folder ready for persistent data and configuration.

For production, you should also plan:

  • Regular backups of your data folder or MongoDB.
  • A trusted TLS certificate for your domain.

Quick checks:

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

Ports, Folders, and Settings

SSH Teams listens on two ports:

  • 8080 for HTTP.
  • 8443 for HTTPS.

You should mount two folders from your host machine into the container:

  • ./nitrate/conf.d:/app/conf.d keeps your configuration and certificates safe.
  • ./nitrate/data:/app/nitrate/data stores the built-in database files (Nitrate mode only).

If you use external MongoDB, you only need the conf.d folder.

You can name the host folder anything you like. For example:

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

Important Settings

The main settings you can change are:

  • HTTP_PORT — the HTTP port inside the container (default 8080).
  • HTTPS_PORT — the HTTPS port inside the container (default 8443).
  • SSHTEAM_PERSISTENCE_BACKEND — choose nitrate or mongo.
  • MONGODB_URI — your MongoDB connection address (only needed for MongoDB mode).

For older setups, SERVER_PORT and SSHTEAM_HTTPS_PORT still work as fallbacks.

Check That It Started

After starting the container:

  1. Open https://localhost:8443 in your browser.
  2. Complete the first-time setup to create your team and admin account.
  3. Log in and check that the dashboard loads.

You can also check the container status:

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

If something goes wrong, see the Troubleshooting Handbook.

Docker Run Examples

With the Built-in Database

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

docker run -d \
    --name sshteam \
    -p 8080:8080 \
    -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=8080 \
    -e HTTPS_PORT=8443 \
    jadaptive/sshteam:latest

With External MongoDB

mkdir -p ./nitrate/conf.d

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

Replace the example MONGODB_URI with your real MongoDB connection details.

Docker Compose Examples

With the Built-in Database

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

With External MongoDB

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:8080"
            - "8443:8443"
        environment:
            SSHTEAM_PERSISTENCE_BACKEND: "mongo"
            HTTP_PORT: "8080"
        HTTPS_PORT: "8443"
        MONGODB_URI: "mongodb://mongo:27017/sshteam"
        volumes:
            - ./nitrate/conf.d:/app/conf.d
        restart: unless-stopped

Start either setup with:

docker compose up -d

Upgrading or Rolling Back

Because your data lives in mounted folders or an external database, upgrading is simple:

  1. Pull the new image.
  2. Recreate the container using the same folders and settings.
  3. Log in and check that everything still works.

To roll back:

  1. Stop the new container.
  2. Start the previous image version with the same folders and settings.
  3. Confirm the dashboard loads.

Troubleshooting Common Issues

  • The container runs but you can’t open the web interface:

    • Check that ports 8080 and 8443 are mapped and not blocked by a firewall.

  • Setup or login behaves unexpectedly:

    • Run docker logs sshteam to look for startup errors.

  • External MongoDB mode won’t connect:

    • Double-check the MONGODB_URI, including host, port, username, and password.
    • If using Compose, make sure the SSH Teams container and MongoDB are in the same Docker network.

  • Browser warns about the certificate:

    • Make sure /app/conf.d is mounted and that a proper TLS certificate is in place for production.