User guide

Getting started

DockBeacon is a self-hosted web app that replaces juggling SSH sessions and docker logs commands. Install the package, open http://<host>:9447, sign in, pick containers, and stream. That HTTP URL is the supported zero-config path for lab and staging. Production puts TLS on a reverse proxy in front of the same port.

1. Install the package Debian/Ubuntu or RHEL/Fedora — see the install page. Fastest: the one-step installer installs, asks standalone or agent, and starts the service.

   curl -fsSL https://dock-beacon.web.app/install.sh -o install.sh
   sudo bash install.sh

   Or add the repo yourself:

   curl -fsSL https://govindsingh9447.github.io/docker-log-viewer-packages/install-apt.sh -o install-apt.sh
   less install-apt.sh
   sudo bash install-apt.sh
   sudo apt-get install docker-log-viewer

2. Configure the service Edit /etc/docker-log-viewer/docker-log-viewer.env, then enable systemd.

   sudo nano /etc/docker-log-viewer/docker-log-viewer.env
   # APP_MODE=standalone
   # SERVER_NAME=my-host
   # PROJECTS_DIR=/home/ubuntu/projects
   # PORT=9447
   # LISTEN_ADDR=0.0.0.0
   
   sudo systemctl enable --now docker-log-viewer

3. Open the UI & sign in Browse to http://<host>:9447. No TLS setup is required for lower environments. On first boot, a temporary password is printed in journalctl -u docker-log-viewer if you did not set AUTH_PASS. The login screen and header show the installed app version (for example v0.2.0) so you can confirm upgrades at a glance.
4. Select containers → View logs Check one or more containers in the left sidebar, then click View logs. Press Start live to tail in real time.

UI tour

The interface has three main areas: header (server switch, health, role), sidebar (containers or stacks), and the main panel (logs or stack editor).

Viewing logs

Step 1 — Pick containers

Use the search box to filter by name, ID, or image. Enable Include stopped to see exited containers. Selected count appears above the list.

Step 2 — View logs

Click View logs (or press Enter when containers are checked). The header shows merged container names as chips — click a chip to mute that container’s lines in the stream.

Step 3 — Live vs fetch

• Start live — WebSocket tail; reconnects automatically on drop.
• Pause — freeze the stream without disconnecting (buffer keeps filling; resume to catch up).
• Fetch — one-shot pull using tail size and time range (Last 15m / 1h / 6h / 24h / custom since-until).

Step 4 — Timestamps & auto-scroll

Toggle Timestamps to prefix each line. Auto-scroll keeps you at the bottom; when you scroll up, a ↓ New lines button appears.

Copy & download

Use Copy for the currently visible buffer, or Download to save a text file. Both respect active filters (muted containers and text/level filters).

Inspect & restart

Inspect opens a drawer with container details. Inspect, Start, Stop, and Restart are visible only to operator and admin roles.

Filter & search

The filter box above the log output searches displayed lines. Press / anywhere (outside inputs) to focus it.

Plain text

Type any substring — matching text is highlighted in amber. Works on the full rendered line including container tags.

Regex mode (.* button)

Click the .* chip to treat the filter as a JavaScript regular expression. Invalid patterns show a toast and fall back safely. Regex preference is saved and included in share URLs (?regex=1).

Log level filter

The level dropdown filters by severity: Errors only, Warnings+, or Info+. Useful when a noisy service floods info lines but you need the failures.

Clickable tokens

UUIDs, container IDs, and IP addresses in log text are underlined — click to insert them into the filter instantly.

JSON highlighting

Structured JSON in log lines is detected automatically (brace-matched; Laravel-style [timestamp] prefixes are skipped).

Pretty vs compact

Toggle Pretty JSON in the filter bar:

• On — indented block with syntax colors (keys, strings, numbers, booleans, null).
• Off — inline compact highlighting without extra padding.

Full-window mode

Click Expand in the filter bar (or press e) for a distraction-free view: only the filter strip and log output remain. Header, sidebar, stats, and main toolbar hide.

• Connection status appears as a compact pill in the filter bar (live / paused / error).
• Press Esc or e again to exit.
• All filter controls (regex, JSON, wrap, font, share) stay available.

CPU & memory stats

When live streaming active containers, a stats strip appears below the log header. Each card shows:

• Container name and current CPU % / memory usage
• Mini sparklines for the last ~60 samples (fixed 0–100% scale so graphs stay comparable)

Cards update in place — no duplicate cards when stats refresh. Stats require Docker stats API access on the host.

PM2 logs

On a host that already runs PM2, the Logs sidebar shows a Docker / PM2 switch. Hosts without a PM2 daemon stay Docker-only. Stacks stays Docker Compose. DockBeacon does not start a PM2 daemon.

• The list shows name, status, restarts, uptime, and memory.
• Stream Out, Err, or Both. Lines are prefixed [app] [out] or [app] [err].
• Live, pause, fetch, filter, wrap, tail, and time range work the same as container logs.
• Operators and admins can start, stop, or restart an app that is already in the list. Viewers cannot. The action asks for confirmation in the page, not a browser dialog.

The service keeps running as docker-log-viewer. Grant it read access to the PM2 log files once, as root:

sudo apt-get install acl
sudo /usr/lib/docker-log-viewer/pm2-grant-access
sudo systemctl restart docker-log-viewer

That sets an ACL on the PM2 log directory and installs a narrow sudo rule. App status uses pm2 jlist. Start, stop, and restart use pm2-ctl, which only runs those three commands for an app from the last list. Re-run the grant command if PM2 is installed after DockBeacon.

Alerts

The control plane checks itself and every agent every 30 seconds. The Alerts button in the header shows how many alerts are new; open it to see what is active (new ones are tagged New) and recent history. Everyone can see alerts. Admins set them up in Settings → Alerts.

• Channels: Slack, Microsoft Teams, Discord (incoming webhooks), or a generic JSON webhook. Use Test to send a sample. Slack and Discord can mention @here or @channel.
• Each rule can wait a few minutes before firing, so short blips stay quiet. Optionally send a Resolved message when it clears.
• Ignore lists containers or apps that should never alert, such as one-off jobs.
• Set DockBeacon address to your public URL so messages link back to the right page.

Webhook URLs are kept on the server and never shown again after you save them. See Security → Alerts and webhooks.

Timeline & Diagnose

Timeline answers "what changed?". For a container or a whole stack it lists starts, stops, crashes, health changes, and who restarted, redeployed, or edited what. Docker events are recorded continuously and kept 14 days.

Diagnose answers "why is it unhealthy?". It reads the health check log, exit code, restart history, memory, recent error lines, sibling containers in the same stack, and host disk, then explains the likely cause in plain words. It is read-only and never shows env values, so viewers can use it too.

Multi-host & groups

Architecture

Add remote servers

1. Open Settings (header) → Servers section.
2. Add display name + URL e.g. http://10.0.1.5:9447, mode agent.
3. Switch hosts from the header. You stay signed in. The agent accepts the control-plane session when AUTH_SECRET is the same on both hosts. Use Test on the server row to check the connection.
4. Use the header dropdown to switch between standalone and agents.

Host groups

When adding a server, set an optional Group (e.g. Production). Servers with the same group name appear as a single merged entry in the server list. Selecting a group streams logs from all hosts in that group into one view — ideal when the same service runs on multiple machines.

Stacks mode

Switch the sidebar to Stacks to manage Docker Compose projects discovered under PROJECTS_DIR on the server. Requires operator or admin role for edits.

Tabs

Lifecycle buttons

After selecting a project: Start, Stop, Restart, or Compose up. Status syncs in the header. Restore from timestamped backups via the backups dropdown.

Save shortcut in stack editor: Ctrl+S / ⌘+S.

Settings & RBAC

Open Settings from the header.

Password

Any signed-in user can change their own password (min 8 characters).

Roles

User management (admin only)

Create users with username, password, and role. Users are stored in the server’s users file (seeded from AUTH_USER / AUTH_PASS on first boot).

Security

Treat DockBeacon as a host admin console. Operator and admin roles can restart containers and edit Compose / .env files — not just read logs. Full details on the security page.

What is implemented

Still out of scope

• In-process TLS — HTTPS stays on Nginx / ALB
• SAML (use OIDC IdPs such as Keycloak / Authentik / Google)

Production deployment

The process always speaks HTTP on :9447. That is intentional: zero-config for lower environments, HTTPS as a reverse-proxy concern in production.

Production layout: Internet → Nginx/ALB (TLS) → standalone control plane on 127.0.0.1:9447 → agents on private Docker hosts.

# /etc/nginx/sites-available/docker-log-viewer
server {
    listen 443 ssl http2;
    server_name logs.example.com;

    # ssl_certificate     /etc/letsencrypt/live/logs.example.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/logs.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9447;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
    }
}

If this hostname already serves another application at /, give DockBeacon its own prefix. Set BASE_PATH=/dockbeacon and proxy the prefix through unchanged:

location /dockbeacon/ {
    proxy_pass http://127.0.0.1:9447;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

1. systemd — sudo systemctl enable --now docker-log-viewer. Keep config in /etc/docker-log-viewer/docker-log-viewer.env.
2. Firewall — allow 443 to the proxy. Allow control plane → agent :9447. Deny 9447 from untrusted networks.
3. Agents — APP_MODE=agent, the same AUTH_SECRET as the control plane, CORS_ORIGINS=https://logs.example.com, UI_URL=https://logs.example.com.
4. Health — GET /health (Docker ping). Back up the users file.
5. Upgrades — see Upgrade (env file is kept; answer N if apt asks about it). Roll back from the package pool.

Share links

Click Share in the filter bar to copy a URL encoding your current state:

• Selected container IDs (including group merges)
• Active server / group
• Filter text and regex mode
• Live vs paused, tail size, timestamps, wrap, JSON pretty preference

Send the link to a teammate with access — opening it restores the same view (they still authenticate).

Keyboard shortcuts

Shortcuts work when logged in and not typing in an input (except / which always focuses the filter).

Configuration reference

Main environment file: /etc/docker-log-viewer/docker-log-viewer.env

Troubleshooting

Cannot sign in

Check sudo journalctl -u docker-log-viewer -n 50 for the bootstrap password. Verify USERS_FILE permissions if you customized auth.

Live stream disconnects

The UI auto-reconnects. If it loops, check reverse-proxy WebSocket support or firewall rules on port 9447.

Agent not listed / CORS errors

On the agent host set CORS_ORIGINS=http://your-control-host:9447 and the same AUTH_SECRET as the control plane, then restart. Add the agent URL in Settings with mode agent and use Test.

PM2 switch is missing

The Docker / PM2 switch appears only when this host already has a live PM2 daemon. DockBeacon does not start one. Install acl, then run sudo /usr/lib/docker-log-viewer/pm2-grant-access and restart the service.

Stacks empty

Ensure PROJECTS_DIR points to a directory containing compose projects and restart the service.

OIDC login fails

Confirm OIDC_REDIRECT_URL matches the IdP callback exactly (including https). Check journal for OIDC errors after restart.

Stats missing

Stats need running containers and Docker stats access. Stopped containers show no sparklines.