Set Up and Harden DockDash for Localtonet Access

Understand what you are deploying

DockDash is a self-hosted dashboard for discovering and monitoring Docker containers, network services, Kubernetes workloads, and manually added endpoints. Its current feature set includes health and resource history, semantic-version-aware image update monitoring, release-note display, notifications, container lifecycle controls, live logs, a file explorer, text-file editing, terminal sessions, and an interactive topology canvas.

These features are useful precisely because DockDash has access to sensitive operational data and controls. A user who reaches a fully configured instance may be able to inspect logs, change container state, edit files, or open a shell inside a container. The effect depends on the connected workloads and permissions, but DockDash should always be treated as a privileged administrative interface.

The repository's Compose service mounts /var/run/docker.sock from the host. This is what allows DockDash to discover and operate local containers. Access to the Docker daemon is highly privileged in practical terms, so an attacker who compromises the dashboard may be able to affect more than the DockDash container itself.

The request path used in this guide

The browser opens the public HTTPS address assigned to the Localtonet HTTP tunnel. Localtonet forwards that request to DockDash on the protected local listener. DockDash then initiates the OIDC authorization flow and handles the callback at /auth/callback. The identity provider decides who may authenticate, while DockDash maintains the application session.

A tunnel provides network reachability. It does not decide who is authorized to use DockDash. The OIDC configuration must remain active whenever the public tunnel is running.

About authenticated reverse proxies

The DockDash authentication documentation also permits deployment behind an authenticated reverse proxy. It names products such as Caddy, Traefik, nginx, oauth2-proxy, Authelia, and Tailscale as possible authentication layers. Those products have different configuration, identity, header, cookie, and routing requirements.

This tutorial does not present a partial proxy configuration as if it were a complete security boundary. If you use that architecture, the proxy must protect every DockDash route, DockDash must not be independently reachable from an untrusted interface, and the Localtonet tunnel must target the authenticated proxy rather than DockDash. The remainder of this guide uses built-in OIDC so that one authentication path can be followed end to end.

Prepare the DockDash host and identity provider

Use a host with a working Docker Engine, the Docker Compose plugin, and Git. The current DockDash repository presents an image-based Compose service, so the normal deployment flow pulls the image referenced by the checked-out Compose file and starts it. It does not require docker compose up --build.

Install Docker using the instructions for your operating system in the official Docker Engine installation guide. If Compose is not already included, use the official Docker Compose installation guidance. Then verify the tools:

docker --version
docker compose version
git --version

The commands should complete successfully before you clone DockDash. Also confirm that your account can communicate with the Docker daemon through the authorization model used on your host. Do not make the Docker socket globally writable to solve a permissions error.

Reserve the local listener

The supplied DockDash Compose configuration publishes the web service on host port 3001. Check running containers and existing listeners before starting it:

docker ps

If another service already owns port 3001, resolve the conflict deliberately. Changing the host port also changes local tests and the Localtonet target. This guide retains port 3001 and later restricts it to loopback.

Prepare an OIDC application registration

DockDash documents compatibility with standard OIDC providers such as Keycloak, Authentik, Authelia, and Google. At the provider, prepare a confidential web application registration. You will need:

• The provider issuer or discovery URL.
• A registered client ID.
• A client secret that can be supplied privately to DockDash.
• An access policy that limits sign-in to the intended users or groups.
• The exact public callback URI, which will be registered after the Localtonet hostname is assigned.

Do not register a container hostname, a private address, or http://127.0.0.1:3001 as the callback for the remote workflow. The identity provider returns the user's browser to the public HTTPS origin, not to DockDash's internal upstream address.

Plan secret storage

The OIDC client secret and DockDash session secret must not be committed to a public repository. Use the secret-management method appropriate to your environment, restrict access to local environment files, and exclude those files from version control. Do not reuse the client secret as the session secret.

Deploy DockDash from a pinned Compose release

The current repository's documented Compose service uses an image declaration rather than a local build declaration. It publishes port 3001, mounts the Docker socket, and mounts the named dockdash-data volume at /app/data. It also includes settings such as LOG_LEVEL and NETWORK_CIDRS.

A Dockerfile exists in the repository, but its presence alone does not establish a supported production source-build workflow. This guide therefore uses the documented image-based Compose path. If a future DockDash release publishes separate source-build instructions, follow that release's instructions and keep the source-build procedure distinct from prebuilt-image deployment.

git clone https://github.com/dougmaitelli/DockDash.git
cd DockDash
git fetch --tags
git checkout --detach v1.5.0
git rev-parse --short HEAD

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs dockdash

The revision check should report f9c2e65 for this baseline. If it does not, stop and investigate whether the tag, repository, or local checkout differs from the reviewed release.

A Git tag pins the Compose file and repository configuration. It does not necessarily prove that every referenced container image is immutable. Record the actual image ID used by the running container as part of your deployment record:

docker inspect dockdash --format '{{.Config.Image}}'
docker inspect dockdash --format '{{.Image}}'

The first command reports the configured image reference. The second reports the local content-addressed image ID used by the container. Preserve both values with the selected DockDash tag, effective Compose configuration, and deployment date.

Verify DockDash locally and restrict its listener

Before enabling authentication or remote access, verify that the base application works on the Docker host. The documented local interface is http://localhost:3001. Open it in a browser on that host or use an existing secure management path if the host is remote.

A command-line request can establish that an HTTP listener responds:

curl -I http://127.0.0.1:3001

An HTTP response does not prove that container discovery, Docker permissions, application data, or authentication works. Complete a browser-based functional check as well.

Local verification checklist

• Confirm that the DockDash interface loads without a connection error.
• Confirm that expected local containers appear after discovery completes.
• Review container status and resource information.
• Open logs for a non-sensitive test container.
• Confirm that the application can read the Docker daemon without recurring permission errors.
• Make a harmless dashboard change, restart DockDash, and verify that the change persists.
• Review the Compose logs for unexpected scan activity or repeated failures.

Do not use a production workload for the first start, stop, terminal, or file-editing test. Validate administrative functions against a disposable container whose interruption cannot affect users or data.

Bind port 3001 to loopback

The repository example publishes 3001:3001, which can make the service reachable through host network interfaces depending on the host firewall and Docker configuration. When the Localtonet client runs on the same host, replace the existing port entry with a loopback-only binding:

ports:
  - "127.0.0.1:3001:3001"

Edit the existing entry rather than adding a second port mapping. Then apply the change without a source build:

docker compose config
docker compose up -d
docker compose ps

Verify that the local request still succeeds. From another machine on the LAN, confirm that direct access to the DockDash host on port 3001 no longer works.

If the Localtonet client runs on another device, 127.0.0.1 refers to that other device and cannot reach DockDash. In that architecture, provide a narrowly restricted network route to DockDash, allow only the Localtonet client device through the host firewall, and avoid broad publication to an untrusted network.

Configure built-in OIDC with the public callback

DockDash enables OIDC when all three required provider settings are present:

• OIDC_ISSUER: the provider issuer or discovery URL.
• OIDC_CLIENT_ID: the registered client identifier.
• OIDC_CLIENT_SECRET: the registered client secret.

The authentication documentation also defines these supporting settings:

• OIDC_REDIRECT_URI supplies an explicit callback when the public URL should not be inferred from request or proxy headers.
• OIDC_SCOPES defaults to openid profile email.
• SESSION_SECRET signs cookies and is generated per process if omitted.
• SESSION_MAX_AGE defaults to 28800000 milliseconds, or eight hours.
• TRUST_PROXY defaults to loopback, uniquelocal.

Set a stable, random SESSION_SECRET in production. If DockDash generates a new value at every process start, existing sessions become invalid after each restart.

Why the tunnel hostname must be selected first

The identity provider needs the exact browser-facing callback before it can complete the authorization flow. For this deployment, the callback has this shape:

https://your-public-host/auth/callback

The public hostname comes from the Localtonet HTTP tunnel configuration. Creating that configuration and starting it are separate actions. The safe sequence is therefore:

1. Create the Localtonet HTTP tunnel configuration and obtain its assigned public HTTPS hostname.
2. Leave the tunnel stopped while DockDash remains unauthenticated.
3. Register the exact public callback at the OIDC provider.
4. Add the same callback and the required OIDC settings to DockDash.
5. Recreate DockDash and inspect its startup logs.
6. Start the tunnel only for a controlled end-to-end authentication test.
7. Use a clean private browser session to verify that login is mandatory.
8. Stop the tunnel immediately if authentication is skipped or fails open.

Do not delete and recreate the tunnel after registering the callback unless you are prepared to update the provider and DockDash configuration. A replacement tunnel may have a different public hostname.

Add the OIDC environment settings

Add the variables to the existing DockDash service's environment section. The following values are placeholders:

environment:
  - LOG_LEVEL=info
  - OIDC_ISSUER=https://auth.example.com/realms/homelab
  - OIDC_CLIENT_ID=dockdash
  - OIDC_CLIENT_SECRET=replace-with-provider-secret
  - SESSION_SECRET=replace-with-a-long-random-value
  - OIDC_REDIRECT_URI=https://your-public-host/auth/callback

Preserve other required environment settings from the release's Compose file. Avoid placing real secrets in screenshots, shell history, public repositories, or support messages. If you use Compose variable interpolation or a local environment file, restrict its filesystem permissions and exclude it from version control.

Apply the environment changes using the image-based deployment path:

docker compose config
docker compose up -d
docker compose ps
docker compose logs dockdash

Be careful with docker compose config when collecting diagnostic output because an effective configuration can contain resolved secrets. Do not paste unredacted output into a public ticket.

Register an exact callback

Register the same complete URI at the identity provider and in OIDC_REDIRECT_URI. Scheme, hostname, port, path, case, encoding, and trailing slash can affect callback matching. The internal upstream http://127.0.0.1:3001 is not equivalent to the public HTTPS callback.

Do not fix a mismatch by allowing broad wildcard redirects. Verify the URI sent in the authorization request, compare it with the provider registration, and correct the public-origin configuration.

Create and test the Localtonet HTTP tunnel safely

Our client application must run on the DockDash host or on another device that can securely reach its protected listener. The client establishes an outbound connection to a Localtonet relay, so the workflow does not require inbound router port forwarding, inbound firewall changes, VPN setup, or a public IP address.

Install the Localtonet client

Create or sign in to your Localtonet account, then use the dashboard-provided client installation path for the operating system on the device that will run the tunnel. Download the current client offered for that platform, install it, launch it, and authenticate the device with its device-specific token. We do not provide an unverified package command here because the installer and commands vary by operating system and client version.

If you do not yet have an account, use the Localtonet registration page. Keep the device token private. Do not commit it, embed it in an image, paste it into screenshots, or share it in support logs.

Follow the current fields and process types in our HTTP tunnel documentation. HTTP tunnels may use a generated subdomain, a selected subdomain where supported, or a custom domain. Check the current documentation before making custom-domain DNS changes.

Perform the end-to-end OIDC test

1. Confirm that DockDash responds locally at http://127.0.0.1:3001.
2. Confirm that the running DockDash container contains the intended OIDC configuration without printing secret values.
3. Confirm that the provider registration contains the exact Localtonet HTTPS callback.
4. Start the Localtonet tunnel.
5. Open the public URL in a new private or incognito browser window.
6. Verify that DockDash redirects to the expected identity provider before showing dashboard content.
7. Authenticate with an explicitly authorized test account.
8. Verify that the browser returns to /auth/callback on the same public hostname.
9. Confirm that the dashboard, logs, and required real-time functions operate after login.
10. Sign out and verify that protected content is no longer accessible.

Repeat the first public test with a second clean browser session. Existing identity-provider and DockDash cookies can make a session appear to bypass login even when it is reusing prior authentication.

Update, back up, and operate the deployment

Routine administration should preserve the selected DockDash version, effective Compose configuration, OIDC registration, secrets recovery process, image identity, and persistent data. Avoid turning a release-pinned installation back into a mutable branch checkout during updates.

Routine Compose operations

docker compose ps
docker compose logs dockdash
docker compose logs -f dockdash
docker compose restart dockdash
docker compose stop dockdash
docker compose start dockdash
docker compose down
docker compose up -d

docker compose down removes the project containers and network but normally retains named volumes. Do not add --volumes unless you deliberately intend to remove persistent DockDash data and have already tested recovery.

Use a deliberate release update procedure

Before an update, read the DockDash release information and compare changes to the Compose file, authentication settings, volume arrangement, and Docker permissions. Then back up the persistent data and stop the Localtonet tunnel so an upgrade is not performed through an actively exposed administrative interface.

Replace vNEXT with a release tag that you have reviewed:

git fetch --tags
git diff v1.5.0..vNEXT -- docker-compose.yml
git checkout --detach vNEXT

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs dockdash

Verify DockDash locally, verify OIDC, and only then restart the Localtonet tunnel for another clean-browser test. Record the new Git commit, configured image reference, and running image ID.

For rollback, retain the previous release tag, its effective Compose configuration, and a compatible backup taken before the update. Check out the previous tag, restore the matching data only when necessary, recreate the service, and verify locally before restoring remote access. Application data written by a newer release may not always be compatible with an older release, so a tested pre-update backup is important.

Back up the named data volume

The reviewed DockDash documentation identifies the persistent mount at /app/data, but it does not publish a DockDash-specific supported backup and restore workflow. The procedure below is therefore a general cold archive of the Docker named volume, not an application-level backup guarantee. Review Docker's volume backup and restore guidance and test recovery on a non-production host.

First discover the actual runtime volume name instead of assuming that it is exactly dockdash-data. Compose may prefix the volume with the project name:

VOLUME_NAME="$(docker inspect dockdash --format '{{range .Mounts}}{{if eq .Destination "/app/data"}}{{.Name}}{{end}}{{end}}')"
printf '%s\n' "$VOLUME_NAME"

If the command returns an empty value, stop and inspect the container mounts. Do not run backup or restore commands against an unidentified volume.

For a consistent cold archive, stop DockDash, mount the volume read-only in a temporary helper container, and write the archive to a host directory:

mkdir -p backups
docker compose stop dockdash

docker run --rm \
  -v "${VOLUME_NAME}:/source:ro" \
  -v "$PWD/backups:/backup" \
  alpine:3.20 \
  sh -c 'cd /source && tar -czf /backup/dockdash-data.tar.gz .'

docker compose start dockdash
ls -lh backups/dockdash-data.tar.gz

Approve and pin helper images according to your own supply-chain policy. Copy the resulting archive to storage that is separate from the Docker host, protect it as potentially sensitive operational data, and apply an appropriate retention policy.

Test restoration without overwriting production first

The safest validation is to create a separate Docker volume on a test host, extract the archive into it, connect it to a compatible DockDash release, and verify that the application starts with the expected data. Avoid treating a successful archive command as proof of recovery.

If an authorized recovery requires restoring into the existing volume, stop DockDash first and preserve the current volume separately. The following operation removes the existing contents before extraction, so verify every variable and archive name:

docker compose stop dockdash

docker run --rm \
  -v "${VOLUME_NAME}:/target" \
  -v "$PWD/backups:/backup:ro" \
  alpine:3.20 \
  sh -c 'find /target -mindepth 1 -maxdepth 1 -exec rm -rf {} + && tar -xzf /backup/dockdash-data.tar.gz -C /target'

docker compose up -d
docker compose ps
docker compose logs dockdash

Verify the restored deployment locally and keep the Localtonet tunnel stopped until application state and OIDC behavior are confirmed. A DockDash volume backup does not back up the containers, databases, bind mounts, named volumes, Kubernetes workloads, or remote Docker hosts displayed in the dashboard. Those workloads still need their own backup procedures.

Keep the attack surface small

• Keep DockDash bound to loopback when the Localtonet client runs on the same host.
• Use identity-provider groups and policies that grant access only to administrators who need it.
• Protect the OIDC client secret, session secret, and Localtonet device token separately.
• Review access after personnel or role changes.
• Use a disposable workload when testing terminal, file-editing, and lifecycle controls.
• Stop the Localtonet tunnel when remote administration is not needed.
• Review DockDash, identity-provider, Docker, and Localtonet state after unexpected activity.
• Keep a record of the release tag, commit, image ID, Compose configuration, and backup date.

Troubleshoot each layer in order

Check the deployment from the inside out: Docker, DockDash, OIDC, Localtonet client, and tunnel. This avoids changing several layers at once and obscuring the original problem.

The Compose image cannot be pulled

Confirm that you checked out the intended release and that docker compose config resolves the image reference expected by that release. Check Docker daemon status, registry connectivity, and any required registry authentication. Do not add --build merely to work around an image pull failure unless the selected DockDash release explicitly documents a source-build workflow.

Port 3001 is already in use

Identify and stop or reconfigure the conflicting service. If you deliberately choose another host port, update the local verification commands and Localtonet target. The DockDash container port remains the value defined by the release's Compose service.

DockDash cannot discover or control containers

Verify that /var/run/docker.sock exists on the host, is mounted at the expected path in the container, and is accessible to the DockDash process. Review logs for permission errors. Do not make the socket globally writable as a shortcut.

Changes disappear after restart

Inspect the running container's mounts and confirm that /app/data is backed by the intended named volume. Confirm that you did not accidentally start a second Compose project with a different project name and therefore a different volume.

OIDC does not activate

All three required values must be present: OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET. Recreate the service after configuration changes and inspect startup logs. When checking effective configuration, redact secret values before sharing output.

The provider reports a redirect URI mismatch

Compare the callback sent in the authorization request with both the provider registration and OIDC_REDIRECT_URI. They must identify the same public HTTPS URI ending in /auth/callback. Do not substitute the local upstream, container name, or loopback address.

The callback URL does not respond

Confirm that the Localtonet client is connected and that the tunnel is running. The provider can return the browser to the public hostname only while that route is available. Also confirm that the hostname still matches the registered callback and that the tunnel targets the current DockDash listener.

Sessions disappear after every DockDash restart

Configure a stable, random SESSION_SECRET. When it is omitted, DockDash generates a new value per process, invalidating cookies signed by the previous process.

The public URL displays DockDash without login

Stop the tunnel immediately. Confirm that the running container has all required OIDC values, that DockDash was recreated after the settings changed, and that you are testing in a clean browser session. Do not reopen the tunnel until unauthenticated access reliably initiates the intended OIDC flow.

The public URL does not respond

Verify the layers in sequence:

1. Confirm that curl -I http://127.0.0.1:3001 receives an HTTP response on the DockDash host.
2. Confirm that the Localtonet client runs on that host or can reach the configured target.
3. Confirm that the intended Localtonet device is connected.
4. Confirm that the HTTP tunnel target uses the correct local IP and port.
5. Confirm that the tunnel has been started rather than only created.

Loopback works on the DockDash host but not from the Localtonet client

Determine where the client actually runs. If it runs in a container, 127.0.0.1 refers to that container. If it runs on another machine, loopback refers to that machine. Install the Localtonet client directly on the DockDash host when practical, or provide a restricted network-reachable listener protected by host firewall rules.

Login succeeds but the application behaves incorrectly afterward

Check DockDash logs, browser developer tools, and identity-provider logs while avoiding disclosure of authorization codes, tokens, cookies, client secrets, state, or nonce values. Confirm that the browser returns to the same public origin that initiated login and that no stale hostname remains in the provider registration or DockDash configuration.

Frequently asked questions