Build a protected Docker operations dashboard before making it remotely reachable
DockDash brings Docker discovery, monitoring, update information, logs, container controls, file access, and terminal sessions into one self-hosted web interface. Those capabilities are useful, but they also make an unauthenticated DockDash deployment inappropriate for exposure to an untrusted network. This guide installs DockDash with its supported Docker Compose workflow, verifies it locally, and then hardens access with either built-in OIDC or an authenticated reverse proxy. Only after authentication is working do we connect the protected HTTP endpoint to Localtonet for remote access without inbound router port forwarding.
📋 What's in this guide
Understand what you are deploying
DockDash is a self-hosted service monitoring and Docker management dashboard. It can discover containers and network services, track health and resource history, monitor container image updates, display release notes, and organize services on an interactive topology canvas. Its Docker-oriented features also include container start, stop, and restart controls, live logs, a container file explorer, text-file editing, and an interactive terminal.
This is not merely a read-only status page. A user who gains access to a fully configured DockDash instance may be able to inspect logs, modify files, open a shell inside containers, or change container state. The exact impact depends on the containers and hosts connected to DockDash, but the dashboard should be treated as an administrative interface.
The standard Compose deployment mounts the Docker socket at /var/run/docker.sock. That socket lets DockDash communicate with the local Docker daemon and is what enables discovery and container operations. Access to a Docker daemon is highly privileged in practical terms, so protecting the web interface is essential.
Do not expose a default DockDash installation to the public internet. Complete the local installation first, then configure and test built-in OIDC or place DockDash behind an authenticated reverse proxy. Create the Localtonet tunnel only after the selected authentication boundary works correctly.
Recommended request path
The secure request path depends on the authentication design you choose. With built-in OIDC, the browser connects to the public Localtonet HTTPS address, the HTTP tunnel forwards the request to DockDash on the local host, and DockDash handles the OIDC login flow. In this model, Localtonet should target the loopback-bound DockDash listener at port 3001.
With an authenticated reverse proxy, the browser still enters through the Localtonet public address, but the tunnel targets the proxy's local listener instead of targeting DockDash directly. The proxy authenticates the user and forwards approved traffic to DockDash. DockDash should not remain separately reachable from untrusted interfaces.
| Layer | Responsibility | Security consideration |
|---|---|---|
| DockDash | Docker discovery, monitoring, update information, logs, files, terminal, and container operations | Treat it as a privileged administrative application |
| OIDC provider or authenticated proxy | Authenticates users before administrative access is granted | Use an exact callback URI and protect all client secrets |
| Localtonet client | Connects the selected local HTTP endpoint to a Localtonet relay | Keep the device token private and run the client on a host that can reach the protected endpoint |
| Localtonet HTTP tunnel | Provides a public HTTPS address for the selected local target | A running tunnel creates reachability, not application authorization |
Prepare the DockDash host
Use a host on which Docker and the Docker Compose plugin are already installed and functioning. The official DockDash workflow builds and starts the repository's included Compose configuration, so the host must be able to build container images and run Compose projects. You also need enough permission to communicate with the local Docker daemon and to mount its socket into the DockDash container.
Git is useful for cloning and later updating the repository. If Git is not available, an archive of the repository can be downloaded and extracted instead, but the working directory must still contain the project's docker-compose.yml, Dockerfile, source files, and related build files.
Before continuing, verify the tools rather than discovering a missing dependency during the build:
docker --version
docker compose version
git --version
The exact Docker installation procedure depends on the host operating system and packaging method. This guide does not assume an undocumented DockDash platform matrix. Use a Docker-supported host where docker compose works, and follow the operating system's appropriate Docker installation process if either Docker check fails.
Network and identity prerequisites
Reserve local TCP port 3001, which is the documented DockDash web port. If another process already uses it, the supplied mapping cannot start unchanged. You can inspect existing listeners with the tools available on your operating system or check running containers with:
docker psFor built-in OIDC, prepare an application registration at an OpenID Connect provider. DockDash documents compatibility with standard OIDC providers such as Keycloak, Authentik, Authelia, and Google. You will need the provider issuer or discovery URL, a client ID, and a client secret. You will also need to register the exact public callback URI once the final public hostname is known.
For the authenticated reverse-proxy option, prepare a proxy or authentication layer that can protect an upstream HTTP application. DockDash documentation names Caddy, Traefik, nginx, oauth2-proxy, Authelia, and Tailscale as examples. Their individual installation and policy syntax differ, so do not copy configuration intended for one proxy into another.
Back up and isolate the host
DockDash stores persistent application data in a named volume in the supplied Compose arrangement. Plan a backup procedure for that data before relying on the dashboard operationally. Also consider placing administrative applications on a dedicated Docker host or restricted management network. Authentication is necessary, but it does not remove the consequences of granting an application access to the Docker socket.
Built-in OIDC and an authenticated reverse proxy are alternative protection patterns. You can build more complex layered designs, but doing so introduces additional callback, header, cookie, and routing considerations. For a straightforward deployment, choose one clear authentication boundary and test it locally before adding public reachability.
Install DockDash with Docker Compose
The supported quick-start path uses the Compose file included in the DockDash repository. The build is performed locally from the checked-out source, and the service is started in detached mode. Run the following steps from the host that will operate DockDash.
Obtain the DockDash repository
Clone the official repository and enter its project directory. Review the checked-out files before running them, especially the Compose file, Dockerfile, volume mounts, published ports, and environment settings.
Review the included Compose configuration
Confirm that port 3001 is available, that the Docker socket mount is intentional, and that the named data volume meets your persistence requirements. Configure the desired network scan range only if it is appropriate for your environment.
Build and start DockDash
Run the documented Compose command from the project directory. Compose builds the application image and starts the service in the background.
git clone https://github.com/dougmaitelli/DockDash.git
cd DockDash
docker compose up -d --build
DockDash's documented Compose arrangement publishes container port 3001 on host port 3001, mounts /var/run/docker.sock into the container, and uses a named volume at /app/data. It also supports environment configuration such as LOG_LEVEL and NETWORK_CIDRS. Do not copy an example network range without checking whether it matches a network you are authorized to scan.
DockDash supports network discovery across configurable CIDR ranges. Set NETWORK_CIDRS only to ranges you own or are explicitly authorized to inspect. A sample private range is not evidence that it matches your LAN, container network, or organizational policy.
Inspect startup state
After Compose returns, check whether the container is running:
docker compose psIf the service is not running or repeatedly restarts, inspect its logs:
docker compose logs dockdash
The service name in the supplied Compose configuration is dockdash. Build failures, unavailable ports, inaccessible Docker sockets, and malformed environment values should be resolved before any authentication or tunneling work begins.
Verify the local DockDash deployment
The documented local interface is available at http://localhost:3001. Open that address in a browser running on the DockDash host. If you are administering a remote server, use an existing secure management path to test the local listener rather than temporarily exposing port 3001 to the internet.
A command-line header request can confirm that the HTTP listener responds:
curl -I http://127.0.0.1:3001A successful response establishes only that an HTTP service is listening. It does not confirm every DockDash feature, Docker permission, discovery range, or authentication rule. Complete a browser-based functional check as well.
Local verification checklist
- Confirm that the DockDash interface loads without browser connection errors.
- Confirm that expected local containers appear after discovery completes.
- Check that container status and resource information are visible where expected.
- Open logs for a non-sensitive test container and confirm that log access works.
- Verify that persistent dashboard changes survive a controlled container restart.
- Check the Compose logs for repeated errors, permission failures, or unexpected scan activity.
Avoid using a production container as the first target for start, stop, terminal, or file-editing tests. If you need to validate administrative controls, create or select a disposable test container whose interruption cannot affect other services.
Reduce the initial listening scope
The example port mapping 3001:3001 ordinarily publishes the service through the host's network interfaces. DockDash specifically recommends binding the published port to loopback when an authenticated reverse proxy is used and clients must not bypass that proxy:
ports:
- "127.0.0.1:3001:3001"A loopback binding is also a sensible starting point when the Localtonet client runs on the same host and will connect directly to DockDash with built-in OIDC. It prevents ordinary remote hosts from reaching port 3001 through a host interface while still allowing a local client to connect.
If the Localtonet client runs on a different device, 127.0.0.1 on that device refers to the Localtonet device itself, not the DockDash host. In that architecture, the client needs a permitted network path to a protected DockDash or reverse-proxy listener. Do not broaden the bind address casually. Use firewall rules and network segmentation appropriate to your environment.
Harden DockDash before remote access
DockDash supports two documented approaches: built-in OIDC and an authenticated reverse proxy. Built-in OIDC keeps login handling inside DockDash. A reverse proxy moves the authentication boundary in front of DockDash and should be the only client allowed to reach the application.
| Approach | Best fit | Localtonet target |
|---|---|---|
| Built-in OIDC | You already operate a standard OIDC provider and want DockDash to manage its own login session | DockDash at 127.0.0.1:3001 when the client is on the same host |
| Authenticated reverse proxy | You already centralize authentication and access policy at a trusted proxy | The proxy's protected local HTTP listener, using the actual port you configured |
| Unprotected direct access | Local-only setup and initial testing on a trusted host | Do not use this model for an internet-reachable tunnel |
Option A: Configure built-in OIDC
DockDash enables OIDC when all three required provider settings are present: OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET. The issuer is the provider issuer or discovery URL. The client ID and secret come from the application registration at your identity provider.
The following optional or supporting settings affect the login flow:
OIDC_REDIRECT_URIsets an explicit callback when request and proxy headers do not produce the correct public URL.OIDC_SCOPESdefaults toopenid profile email.SESSION_SECRETsigns cookies. If omitted, DockDash generates a new value per process.SESSION_MAX_AGEdefaults to28800000milliseconds, which is eight hours.
Add the variables to the DockDash service's existing environment section in the Compose file. Preserve the rest of the service configuration:
environment:
- 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/callbackThe values above are placeholders. Do not commit a real client secret or session secret to a public repository. Use your normal secret-management process and restrict access to any local environment or Compose override files containing credentials.
Set a stable, random SESSION_SECRET for production. If it is omitted, DockDash generates a new value at startup, invalidating existing sessions whenever the process restarts. Do not reuse the OIDC client secret as the session secret.
Make the callback URI exact
When the final public address is known, the explicit DockDash callback takes this form:
https://your-public-host/auth/callback
Register that exact value with the identity provider and use the same value for OIDC_REDIRECT_URI. Scheme, hostname, port, path, case, encoding, and trailing slash can affect callback matching. The local upstream address, such as http://127.0.0.1:3001, is not the browser-facing callback and should not replace the public URI in a remote deployment.
If you use a generated Localtonet subdomain, create the HTTP tunnel configuration first so that you can obtain its public address, but do not start public access until authentication is configured. Add the resulting HTTPS callback to the OIDC provider and DockDash, rebuild or recreate the DockDash service as needed, test the login flow, and only then start or retain the public tunnel.
After changing the Compose environment, apply the configuration:
docker compose up -d --buildOpen the local interface and confirm that unauthenticated access initiates the expected login flow. Complete a sign-in, sign out, and sign in again. Restart DockDash and verify that the stable session-secret configuration behaves as intended.
Option B: Use an authenticated reverse proxy
In this design, the proxy authenticates the browser before forwarding requests to DockDash. Bind DockDash to loopback if the proxy runs directly on the host:
ports:
- "127.0.0.1:3001:3001"If the proxy runs on a separate Docker network, DockDash documentation recommends not publishing the DockDash port at all. Connect the proxy and DockDash directly to that Docker network, then address DockDash by its service identity and internal port from the proxy. The exact network and proxy configuration depends on the selected proxy and is not specified by DockDash's authentication guide.
Configure the proxy to require authentication for every DockDash route, including callback, API, WebSocket, and other application paths required by the UI. Test direct access to DockDash from an untrusted interface and confirm that it fails. Then test the proxy endpoint and confirm that unauthenticated requests are challenged or redirected according to your authentication policy.
Limit trusted proxy scope
DockDash defaults TRUST_PROXY to loopback, uniquelocal. Use true only when every upstream proxy that can reach DockDash is trusted. An overly broad trust configuration can let a client spoof forwarded connection information.
The proxy should deliberately set or overwrite the forwarded host, scheme, port, and client-address information expected by the application. Do not blindly trust forwarded headers supplied by an internet client. When callbacks or secure cookies depend on the public origin, explicitly configure the public callback rather than weakening identity-provider redirect checks.
If Localtonet targets DockDash directly while authentication exists only on a separate reverse proxy, remote users bypass the proxy. In the reverse-proxy design, point the Localtonet HTTP tunnel at the authenticated proxy listener, not port 3001, and remove or restrict every alternate route to DockDash.
Provide remote HTTP access with Localtonet
Once the protected local endpoint works, Localtonet can make it remotely reachable. Our client application runs on a device that can reach DockDash or the authenticated proxy and establishes an outbound connection to a Localtonet relay. This avoids inbound router port forwarding, public-IP requirements, firewall changes for inbound exposure, and VPN setup.
An HTTP tunnel provides a public HTTPS address for the local HTTP target. The tunnel carries traffic to the selected endpoint, but it does not replace DockDash authentication. Keep OIDC or the authenticated proxy enabled for the entire time the tunnel is running.
Install and run the Localtonet client
Install our client on the DockDash host or another device that can securely reach the protected local endpoint. Keep the client running whenever remote access is required.
Authenticate the intended device
Use the device-specific authentication token supplied through your Localtonet account. Never place that token in this article's example commands, source control, screenshots, support tickets, or shared configuration.
Select an available relay server
Select a currently available relay server or region from the dashboard. Availability can vary, so obtain the current server value from the product instead of copying a hardcoded server code.
Create the HTTP tunnel
Set the local target to the protected endpoint. For built-in OIDC on the same host, this is normally local IP 127.0.0.1 and port 3001. For an authenticated reverse proxy, use that proxy's actual local address and configured listener port instead.
Start and test the tunnel
Creating a tunnel does not start it. Press Start, open the assigned public HTTPS address in a private browser window, and confirm that authentication is required before DockDash content or administrative functions are available.
Consult our Localtonet HTTP tunnel documentation while configuring the current dashboard fields. HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Exact custom-domain DNS requirements should be checked against current documentation before changing DNS.
Use the correct local target
- Built-in DockDash OIDC, same host: target
127.0.0.1and port3001. - Authenticated host proxy: target the proxy's bound local address and its configured port.
- Proxy in Docker: ensure the Localtonet client can actually reach the proxy listener from its execution environment.
- Client on another machine: use a restricted network-reachable address, not that machine's loopback address.
Test with a fresh private browser session so an existing OIDC cookie does not conceal an authentication bypass. The first visible result should be the intended identity-provider or proxy authentication flow. After signing in, test the main dashboard, logs, and any real-time features you expect to use.
A Localtonet tunnel is available only while the selected client is connected and the tunnel is running. Stop the tunnel when remote administration is no longer required, or delete it when the configuration should not be reused.
Operate DockDash safely
Routine operation should include checks at the application, container, authentication, and tunnel layers. When access fails, separating these layers helps identify whether the problem is DockDash, Docker, the identity provider, the reverse proxy, the Localtonet client, or the tunnel lifecycle.
Common Docker Compose operations
docker compose ps
docker compose logs dockdash
docker compose logs -f dockdash
docker compose restart dockdash
docker compose down
docker compose up -d --build
docker compose down stops and removes the Compose containers and network. Named volumes are retained unless you explicitly request their removal. Do not add a volume-removal option unless you intend to delete persistent DockDash data and have a verified backup.
Before updating, review DockDash release notes and repository changes, especially migrations, authentication changes, Docker permissions, and Compose modifications. Back up persistent data, update the checked-out source using your chosen Git workflow, and rebuild with the documented Compose command. Verify locally before reopening remote access.
Keep the attack surface small
- Leave DockDash bound to loopback or an isolated Docker network whenever the architecture permits it.
- Do not publish port 3001 separately if all access is supposed to pass through an authenticated proxy.
- Use least-privilege identity-provider groups and access policies.
- Protect the OIDC client secret, session secret, and Localtonet device token.
- Review users and sessions after personnel or role changes.
- Use a disposable container when testing terminal, file-editing, and lifecycle controls.
- Stop the Localtonet tunnel when remote administration is not needed.
- Review DockDash and container logs for unexpected administrative activity.
Backup scope
Back up the DockDash persistent data volume according to your Docker backup process. A dashboard backup does not automatically back up every managed container, bind mount, Docker volume, database, or remote host. Continue using workload-specific backup and restore procedures for the services displayed in DockDash.
Test restoration in a non-production environment. A backup that has never been restored is not sufficient evidence that recovery will work. Record the DockDash version, Compose configuration, environment settings, secret-recovery process, and identity-provider application configuration alongside the operational documentation.
Troubleshoot installation, authentication, and tunneling
The Compose build fails
Confirm that the command is running from the repository directory containing docker-compose.yml. Check available disk space, Docker daemon status, and network access required to obtain build dependencies. Read the complete build error rather than repeatedly restarting the command.
Port 3001 is already in use
Stop or reconfigure the conflicting service before starting DockDash. Do not choose a replacement host port without also updating every local test, reverse-proxy upstream, firewall rule, and Localtonet target that depends on it. The documented browser address assumes port 3001.
DockDash cannot discover or control containers
Verify that the Docker socket exists on the host, is mounted at /var/run/docker.sock in the container, and is accessible to the DockDash process. Review the container logs for permission failures. Do not solve socket errors by granting broad host permissions without understanding the resulting privilege.
OIDC is not enabled
All three required settings must be present: OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET. Check the effective Compose configuration and container environment without printing secret values into shared logs. Recreate the service after configuration changes.
The provider reports a redirect URI mismatch
Compare the URI sent in the authorization request with the URI registered at the provider and the value in OIDC_REDIRECT_URI. They should describe the same public HTTPS callback, including /auth/callback. Do not register a container hostname, loopback address, or internal HTTP upstream as the remote browser callback.
Login works locally but fails through the public URL
Set OIDC_REDIRECT_URI explicitly to the public callback and verify forwarded host and scheme handling. If a reverse proxy is involved, ensure it overwrites forwarded metadata consistently and that DockDash trusts only the intended proxy chain. Check browser cookie behavior and confirm that the callback reaches the same deployment that started the login flow.
Sessions disappear after every restart
Configure a stable, random SESSION_SECRET. DockDash generates a new value per process when this setting is omitted, so cookies signed before a restart no longer validate afterward.
The public address bypasses the login page
Stop the Localtonet tunnel immediately. Confirm whether it targets DockDash directly instead of the authenticated proxy. For built-in OIDC, verify that all required OIDC settings are active in the running container. Do not restart public access until a private browser session is forced through authentication.
The Localtonet URL does not respond
Verify the layers in order. Confirm that DockDash or the proxy responds locally, that the Localtonet client device can reach the configured target, that the intended device is connected, and that the tunnel has been started. Recheck the local IP and port. A tunnel that has merely been created is not yet running.
The tunnel works only when targeting a non-loopback address
This usually means the Localtonet client is not running in the same network namespace or on the same host as DockDash. 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 device, loopback refers to that other device. Provide a narrowly restricted network path to the protected endpoint instead of exposing DockDash broadly.
Frequently asked questions
Does DockDash require authentication by default?
No. DockDash does not enforce authentication by default. Configure its built-in OIDC support or place it behind an authenticated reverse proxy before exposing it to an untrusted network.
What local address does DockDash use?
The documented Compose deployment makes the web interface available at http://localhost:3001. For a same-host Localtonet client and built-in OIDC, the HTTP tunnel can normally target 127.0.0.1:3001.
Should Localtonet target DockDash or the reverse proxy?
Target DockDash directly only when DockDash's own OIDC authentication is protecting it. If authentication is implemented by a reverse proxy, target the proxy's protected listener. Otherwise the tunnel would bypass the authentication layer.
What OIDC settings are required?
DockDash requires OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET to enable OIDC. A stable SESSION_SECRET is strongly recommended, and OIDC_REDIRECT_URI should be set explicitly when the public URL cannot be inferred correctly.
What callback path does DockDash use for OIDC?
The documented explicit callback uses /auth/callback. Register the complete public URI, such as https://your-public-host/auth/callback, exactly at the identity provider and configure the same value in DockDash.
Does a Localtonet HTTP tunnel replace OIDC?
No. The tunnel provides network reachability and a public address for the selected local HTTP target. DockDash OIDC or the authenticated reverse proxy remains responsible for deciding who may use the administrative interface.
Why should the Docker socket mount be treated carefully?
The Docker socket permits communication with the Docker daemon and enables DockDash features such as discovery, logs, terminal access, file operations, and container controls. Compromise of an application with that access can have serious host and workload consequences, so the interface requires strong authentication and restricted network exposure.
Will the public DockDash URL remain available if the Localtonet client stops?
No. The tunnel is available only while the selected Localtonet client is connected and the tunnel is running. Creating the tunnel configuration alone does not start it.
Connect your protected DockDash deployment
After DockDash works locally and every remote request is forced through OIDC or your authenticated proxy, create a Localtonet HTTP tunnel to the protected endpoint and test it in a fresh private browser session.
Get Started Free →
