Connect Docker Host Dashboard SSH TLS: The Complete, Reliable Setup Guide

To connect Docker host dashboard SSH TLS or plain-socket style, Stashboard offers three transports: Local socket, SSH tunnel and Remote TCP+TLS. Your pick decides what the host needs, what you expose on the network, and which features you get, from compose-aware updates to the browser host terminal. 🐳

The Stashboard overview introduces the dashboard, and the Docker update monitoring guide covers watches and notifications. This post covers the connect Docker host dashboard SSH TLS layer underneath both: what each transport needs, its security trade-offs, what it unlocks, and how to add, edit and verify it on the Docker instances page that V5.9 redesigned.

Connect Docker Host Dashboard SSH TLS: The Three Transports

Every Docker connection belongs to your account and has a name, such as home-server. One connection can back many services and watches. Here’s how each option reaches the daemon:

• Local socket: Stashboard talks to /var/run/docker.sock inside its own container, bind-mounted from the host. It only reaches the host Stashboard runs on, and nothing listens on the network.
• SSH tunnel: Stashboard opens an SSH connection with a private key, runs docker system dial-stdio on the remote host and sends the Docker API through it, like docker -H ssh:// does. Without a remote docker CLI it falls back to socat. No Docker port is opened.
• Remote TCP+TLS: the remote daemon listens on tcp://…:2376 with mutual TLS, and Stashboard presents a client certificate signed by your CA. No SSH login, but an open port.

The connect Docker host dashboard SSH TLS rule of thumb: Local socket for the machine running Stashboard, SSH tunnel for every other host, and TCP+TLS only when SSH isn’t an option.

Which Features Each Connect Docker Host Dashboard SSH TLS Transport Unlocks 🔓

Monitoring works on every connect Docker host dashboard SSH TLS transport. The more a feature needs files or a shell on the host, the pickier it gets:

• Update monitoring and alerts: all three. Digest checks, badges and email, Telegram or Apprise alerts only read from the daemon.
• Update now (raw recreate): all three. Stashboard pulls, stops, removes, recreates and starts the container through the Docker API.
• Compose-aware Update now and Update project: Local socket only. The bundled docker compose CLI runs pull and up -d in the project folder, so the stacks root must be mounted into Stashboard. SSH and TCP+TLS fall back to the raw recreate, as the compose-aware update guide explains.
• Visual Compose editor, New project, Save & apply: Local socket (with the stacks root mounted) and SSH tunnel. Over SSH, Stashboard edits the files on the remote host and runs docker compose there, with no mount, even though Update now stays a raw recreate. TCP+TLS has no file access.
• Host terminal: SSH tunnel only. A Local socket shell would land in Stashboard’s own container, and TCP+TLS has no shell. See the browser SSH terminal guide.
• Container exec: all three, because exec goes through the daemon. See the container exec guide.
• Image prune and the Storage widget: all three.
• Deleting the project folder when you remove a container: SSH tunnel only.

Security Trade-offs When You Connect Docker Host Dashboard SSH TLS Hosts ⚖️

No connect Docker host dashboard SSH TLS choice is risk-free: Docker API access is root on that host, as Docker’s daemon attack surface notes explain. The transports differ in where that power sits.

Local socket

• Nothing is exposed on the network; the only way in is through Stashboard.
• The socket is root on the host. Whoever controls Stashboard can start a privileged container.
• :ro isn’t a security boundary. It stops the socket file being changed, not the API calls sent through it. The Stashboard docs suggest :ro for tracking-only setups and a plain mount for Update now; treat both as root.

SSH tunnel

• No Docker port on the network, only SSH, which you already harden.
• Key-only authentication. The key and passphrase are encrypted at rest with AES-256-GCM, and each check opens a short-lived connection, then closes it.
• The SSH user needs socket access, usually through the docker group, which is root-equivalent. A leaked key is a root compromise.
• ⚠️ Stashboard doesn’t pin the SSH host key, so it can’t detect a spoofed host. Keep SSH connections on your LAN or a VPN.

Remote TCP+TLS

• A port is open, but mutual TLS rejects any client without a certificate signed by your CA.
• Stashboard checks the daemon’s certificate against the CA you paste, and only that: no hostname match, no revocation check. Use a dedicated CA for Docker.
• ⚠️ Never expose the unencrypted port 2375. Firewall 2376 so only Stashboard’s IP can reach it.
• The client key is root on that host, encrypted at rest like the SSH key.

Prerequisites

Before you connect Docker host dashboard SSH TLS or socket connections, have:

• A current Stashboard install. The steps follow the 10.x UI.
• Shell access to the Stashboard machine and to each remote host.
• For SSH: an SSH server reachable from Stashboard, with the docker CLI or socat on the host, plus the Compose v2 plugin if you want the Compose editor there.
• For TCP+TLS: root on the remote host, openssl, and control of its firewall.
• A backup of the stashboard-data volume. Unless you set STASHBOARD_ENCRYPTION_KEY yourself, the key that encrypts connection secrets lives there, under /app/Data/.secrets.

Step-by-Step: Add a Local Socket Connection

Local socket is the simplest connect Docker host dashboard SSH TLS setup, because there’s nothing to authenticate.

1. Mount the socket into Stashboard

In Stashboard’s docker-compose.yml, add the socket under volumes:. The stacks-root line is optional; it powers compose-aware updates and the Compose editor. Use the same path on both sides and you won’t need a mapping.

services:
  app:
    volumes:
      - stashboard-data:/app/Data
      - stashboard-uploads:/app/wwwroot/uploads
      - /var/run/docker.sock:/var/run/docker.sock
      - /opt/stacks:/opt/stacks

2. Recreate Stashboard

docker compose up -d

3. Add the connection

On the Docker page, click Add connection in the top-right corner. In the Add Docker connection dialog:

1. Name: something memorable, like home-server. Names must be unique in your account.
2. Docker host: Local socket.
3. Compose path mapping (optional): leave both fields blank if the stacks root has the same path on both sides. For /opt/stacks:/compose, enter /opt/stacks as the host prefix and /compose as the container prefix.
4. Click Test connection, then Save connection.

⚠️ Set both prefixes or neither. A single prefix is ignored, so Stashboard looks for the host path inside its container, and a compose-aware update can end as RecreateFailed.

Step-by-Step: Add an SSH Tunnel Connection

SSH tunnel is the connect Docker host dashboard SSH TLS default for remote machines, since nothing new listens on the network.

1. Create a dedicated key

ssh-keygen -t ed25519 -f ./stashboard_docker -C stashboard
ssh-copy-id -i stashboard_docker.pub [email protected]

2. Give the SSH user socket access

sudo usermod -aG docker docker

Log out and back in. From the Stashboard machine, this must list containers without a password prompt:

ssh -i stashboard_docker [email protected] docker ps

3. Fill in the form

Click Add connection and set Docker host to SSH tunnel:

• SSH host, SSH port (default 22) and SSH username.
• SSH private key (PEM): paste the whole stashboard_docker file, including the BEGIN and END lines. Ed25519, RSA and ECDSA keys work.
• Private key passphrase (optional): only if the key has one.
• Remote socket path: defaults to /var/run/docker.sock.

⚠️ The Remote socket path only matters without the docker CLI. When the remote has docker, Stashboard runs docker system dial-stdio, which follows that user’s Docker context, not this field. For rootless Docker, run docker context use rootless as the SSH user. On a socat-only host, set the field to /run/user/<uid>/docker.sock.

4. Decide on the host terminal

Of every connect Docker host dashboard SSH TLS option, only SSH shows Allow host terminal, and it’s off by default. Leave it off unless you need a shell on the host; it also needs Settings → Host terminal turned on.

5. Test and save

Click Test connection, wait for “Docker host reachable”, then Save connection. Your connect Docker host dashboard SSH TLS tunnel is live.

Step-by-Step: Add a Remote TCP+TLS Connection

TCP+TLS is the most work of any connect Docker host dashboard SSH TLS option, so follow the order exactly.

1. Generate the certificates

On the remote host, as root, follow Docker’s protect the daemon socket recipe. Replace 192.168.1.50 with the host’s IP:

mkdir -p /etc/docker/certs && cd /etc/docker/certs
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -days 3650 -key ca-key.pem -out ca.pem -subj "/CN=docker-ca"
openssl genrsa -out server-key.pem 4096
openssl req -new -key server-key.pem -out server.csr -subj "/CN=$(hostname)"
echo "subjectAltName = IP:192.168.1.50,IP:127.0.0.1" > extfile.cnf
openssl x509 -req -days 3650 -in server.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out server-cert.pem -extfile extfile.cnf
openssl genrsa -out client-key.pem 4096
openssl req -new -key client-key.pem -out client.csr -subj "/CN=client"
echo "extendedKeyUsage = clientAuth" > extfile-client.cnf
openssl x509 -req -days 3650 -in client.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out client-cert.pem -extfile extfile-client.cnf
chmod 0400 ca-key.pem server-key.pem client-key.pem

2. Make the daemon listen with TLS

⚠️ Create the certificates first. If a file is missing, dockerd won’t start, and you lose the local socket too. If /etc/docker/daemon.json already sets hosts, remove it, or the daemon refuses to start.

mkdir -p /etc/systemd/system/docker.service.d
tee /etc/systemd/system/docker.service.d/override.conf <<'EOF'
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2376 --containerd=/run/containerd/containerd.sock --tlsverify --tlscacert=/etc/docker/certs/ca.pem --tlscert=/etc/docker/certs/server-cert.pem --tlskey=/etc/docker/certs/server-key.pem
EOF
systemctl daemon-reload && systemctl restart docker

3. Open the port to Stashboard only

Replace 192.168.1.10 with the IP of the Stashboard machine:

sudo ufw allow from 192.168.1.10 to any port 2376 proto tcp

4. Fill in the form

Click Add connection and set Docker host to Remote TCP+TLS:

• Host URL: tcp://192.168.1.50:2376.
• TLS CA cert (PEM): the contents of ca.pem.
• TLS client cert (PEM): the contents of client-cert.pem.
• TLS client key (PEM): the contents of client-key.pem.

Click Test connection, then Save connection to finish the connect Docker host dashboard SSH TLS setup.

⚠️ Paste the CA that signed the server certificate. The recipe uses one CA for both sides, but with an existing PKI the wrong CA is the most common failure.

Edit, Switch or Delete a Connection ✏️

Since the V5.9 redesign, every connect Docker host dashboard SSH TLS connection gets a pill in the connection switcher, with its running/total count and an amber badge for pending updates, plus a summary card with a status dot, transport, endpoint and container count.

To edit a connect Docker host dashboard SSH TLS entry, click ⋮ on its host card, or right-click the card, and choose Edit. The same menu shows New project on Local socket and SSH hosts and Terminal on SSH hosts. The Edit connection dialog is the Add form with a few extras:

• Saved secrets stay hidden. Each certificate, key and passphrase field shows a Keep / Set / Clear selector and “Using saved value”. Pick Set only to replace one.
• Test before you save. Test connection uses the saved secret for any field left on Keep, so you can test a new host URL without pasting certificates again.
• ⚠️ Switching the type drops the old type’s settings. Saving an SSH connection as another type clears its SSH key and host-terminal opt-in; leaving Local socket clears the Compose path mapping.
• Delete sits at the bottom of the form. Stashboard refuses to delete a connection that services still use, and deleting never touches the Docker host or its containers.

How to Verify Your Connect Docker Host Dashboard SSH TLS Setup ✅

Run these checks for every connect Docker host dashboard SSH TLS setup you add:

1. Test connection: expect “✓ Docker host reachable”. It’s a Docker API ping, so it proves reachability and credentials, not write access.
2. Host card: the dot turns green once the container list loads, next to the transport (localsocket, ssh or tcptls) and endpoint.
3. Command-line cross-check: from the Stashboard machine, run the line for your transport:

docker exec stashboard-app ls -l /var/run/docker.sock
ssh -i stashboard_docker [email protected] docker ps
curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://192.168.1.50:2376/_ping

4. Feature check: open the host’s ⋮ menu. SSH hosts show Terminal and New project, Local socket hosts show New project, and TCP+TLS hosts show only Edit.
5. Write check: run Update now on a non-critical watch. A Success row in its Update history proves write access.

Troubleshooting 🔧

Most connect Docker host dashboard SSH TLS failures come down to one of these:

• Local socket: “permission denied” on the socket. The image runs as a non-root stashboard user, and the host socket usually belongs to the docker group. Add that group’s ID, from getent group docker | cut -d: -f3, to the service in docker-compose.yml:

    group_add:
      - "988"

• “SSH connection failed: Permission denied (publickey)”. The public key isn’t in the user’s ~/.ssh/authorized_keys, or that file’s permissions are too loose.
• SSH connects, Docker refuses. The SSH user isn’t in the docker group yet, or hasn’t logged in again since.
• Test connection hangs, then shows 504. A firewall is silently dropping packets to 22 or 2376, and your reverse proxy gives up first. nc -vz -w 3 192.168.1.50 2376 should succeed within a second.
• TCP+TLS handshake errors. The CA field holds the wrong CA, a certificate expired, or the client certificate lacks extendedKeyUsage = clientAuth.
• “No docker compose CLI was found on the host.” The Compose editor over SSH needs the Compose plugin on the remote host.
• A compose-aware update ends as RecreateFailed. The project folder isn’t reachable inside Stashboard. Check the stacks-root mount and the path mapping.

Risks to Keep in Mind ⚠️

Every connect Docker host dashboard SSH TLS connection carries these risks:

• Your Stashboard login is root on every connected host. Protect it with TOTP (V10.3) or SSO (V10.5), and reach Stashboard over a VPN, as in the secure remote access guide.
• Backups are secrets. A data-volume backup holds the encrypted keys and, unless you set your own, the key that decrypts them.
• Revocation is manual. To cut off SSH, remove the key from authorized_keys. TLS has no revocation check here, so a leaked client key means a new CA and new certificates.
• One compromised container can mean the host. Anything with the socket mounted controls the daemon, so work through the Docker security checklist.

Connect Docker Host Dashboard SSH TLS FAQ

Which transport should the Stashboard host itself use?

Local socket. Of the three connect Docker host dashboard SSH TLS transports, it’s the only one with compose-aware updates, and it exposes nothing.

Can I connect Docker host dashboard SSH TLS style to a remote host without opening a Docker port?

Yes. Use an SSH tunnel: it needs only SSH access, and the Docker API never listens on the network.

Does the SSH tunnel support password logins?

No. Every connect Docker host dashboard SSH TLS tunnel authenticates with a private key, optionally protected by a passphrase.

Why doesn’t my TCP+TLS host show Terminal or New project?

Both need a shell or file access on the host, and a TCP+TLS connection only reaches the Docker API. Switch that host to an SSH tunnel if you need them.

Bottom Line

Three connect Docker host dashboard SSH TLS transports, three trade-offs. Local socket is the simplest and the only route to compose-aware updates, but it reaches just the Stashboard host. SSH tunnel is the best default for remote hosts: no open Docker port, plus the host terminal and the Compose editor. TCP+TLS works where SSH can’t, at the cost of an open, certificate-guarded port. However you connect Docker host dashboard SSH TLS or socket access, test it, check the host card, and remember that every connection is root on that host. 🚀

New to Stashboard? Start with the homelab dashboard overview. Stashboard is open source: code on GitHub, image on Docker Hub.