Configuration

Configure LogDeck to match your environment and security requirements.

Environment Variables

LogDeck is configured entirely through environment variables. This makes it easy to deploy across different environments with different configurations.

Server Configuration

Configure the backend server and Docker connection

DOCKER_HOSTSOptional

Comma-separated list of Docker hosts to manage. Each entry uses name=host format and supports unix://, tcp://, and ssh:// URLs.

Default: local=unix:///var/run/docker.sock

DOCKER_HOSTS=local=unix:///var/run/docker.sock

Examples:

# Local only
DOCKER_HOSTS=local=unix:///var/run/docker.sock

# Mix of local and remote TCP
DOCKER_HOSTS=local=unix:///var/run/docker.sock,staging=tcp://192.168.1.100:2375

# SSH connection (mount your SSH keys or forward agent)
DOCKER_HOSTS=local=unix:///var/run/docker.sock,prod=ssh://deploy@prod.example.com

Host names appear in the UI and in the container list so you always know which Docker daemon you are interacting with.

Authentication (Optional)

Secure your LogDeck instance with JWT-based authentication

Authentication is completely optional

If these variables are not set, LogDeck will run without authentication. This is fine for local development or trusted networks.

JWT_SECRETRequired for auth

Secret key used to sign JWT tokens. Must be at least 32 characters long.

JWT_SECRET=your-super-secret-key-change-this-to-something-random-min-32-chars

Generate a random secret:

openssl rand -base64 32

ADMIN_USERNAMERequired for auth

Admin username for logging in.

ADMIN_USERNAME=admin

ADMIN_PASSWORD_SALTRequired for auth

Random salt for password hashing. Use a strong, random string.

ADMIN_PASSWORD_SALT=your-random-salt-change-this

Generate a random salt:

openssl rand -hex 32

ADMIN_PASSWORDRequired for auth

SHA256 hash of (password + salt). Do not use plain text!

ADMIN_PASSWORD=your-sha256-hash

Coolify Integration (Optional)

Persist environment variable changes across Coolify redeployments

Only needed for Coolify-managed servers

If you deploy containers through Coolify, enabling this integration ensures that environment variable changes made in LogDeck are synced to Coolify and persist across redeployments. Without it, changes are lost when Coolify redeploys.

COOLIFY_CONFIGSRequired for Coolify

Per-host Coolify configuration. Each entry maps a Docker host name (from DOCKER_HOSTS) to a Coolify instance URL and API token. Generate API tokens from your Coolify dashboard under Settings → API Tokens.

# Format: hostName|apiURL|apiToken,hostName|apiURL|apiToken
# Single host
COOLIFY_CONFIGS=local|https://your-coolify-instance.com|your-api-token

# Multiple hosts with different Coolify instances
COOLIFY_CONFIGS=prod|https://coolify-prod.example.com|token-abc,staging|https://coolify-staging.example.com|token-xyz

How it works

LogDeck detects Coolify-managed containers automatically via Docker labels
When you update environment variables, changes are synced to the Coolify API
Sync is best-effort: if the Coolify API is unreachable, the container update still succeeds
Coolify-managed containers are marked with a badge in the container list

Password Hashing

For security, LogDeck uses SHA256 hashing with a salt. Never use plain text passwords in the ADMIN_PASSWORD environment variable. The password is hashed as SHA256(password + salt).

Quick Method: Using Shell Commands

Generate both salt and password hash in one go:

Step 1: Generate a random salt

openssl rand -hex 32

Save this output as your ADMIN_PASSWORD_SALT

Step 2: Generate the password hash

# Replace YOUR_PASSWORD and YOUR_SALT with your actual values
echo -n "YOUR_PASSWORDYOUR_SALT" | shasum -a 256 | awk '{print $1}'

# Example: If password is "admin123" and salt is "mysalt", run:
echo -n "admin123mysalt" | shasum -a 256 | awk '{print $1}'

Save this output as your ADMIN_PASSWORD

Alternative: Using Python

import hashlib

password = "your-password"
salt = "your-salt"
hash_value = hashlib.sha256((password + salt).encode()).hexdigest()
print(hash_value)

Alternative: Using Node.js

const crypto = require('crypto');

const password = 'your-password';
const salt = 'your-salt';
const hash = crypto.createHash('sha256').update(password + salt).digest('hex');
console.log(hash);

Important Security Notes

• Generate a unique, random salt for each deployment

• Never use the same salt across different environments

• Keep your salt and password hash secure - treat them like passwords

• The hash format is: SHA256(password + salt), where strings are concatenated directly

Complete Example

Here's a complete docker-compose.yml with all configuration options:

services:
  logdeck:
    image: amoabakelvin/logdeck:latest
    container_name: logdeck
    ports:
      - "8123:8080"
    volumes:
      # Mount Docker socket for container management
      - /var/run/docker.sock:/var/run/docker.sock
      # Mount /proc for system stats
      - /proc:/host/proc:ro
    environment:
      # Docker hosts (local + remote example)
      DOCKER_HOSTS: "local=unix:///var/run/docker.sock,prod=ssh://deploy@prod.example.com"

      # Authentication (optional - remove to disable auth)
      JWT_SECRET: "your-super-secret-key-min-32-characters-long"
      ADMIN_USERNAME: "admin"
      ADMIN_PASSWORD_SALT: "your-random-salt-change-this"
      ADMIN_PASSWORD: "your-sha256-hash"

      # Coolify integration (optional - host names must match DOCKER_HOSTS)
      # COOLIFY_CONFIGS: "local|https://your-coolify-instance.com|your-api-token"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Read-Only Mode

LogDeck supports a read-only mode that prevents any container management operations. This is useful in production environments where you want to view logs but not modify containers.

Read-only mode is controlled via a feature flag in the backend code. When enabled, all mutating operations (start, stop, restart, remove, env updates) will be blocked.

Docker Socket Permissions

LogDeck needs access to the Docker socket to interact with containers. Here are some important considerations:

Security Best Practices

Run LogDeck only on trusted networks
Enable authentication if exposing LogDeck to untrusted users
If you only need log viewing (no container management), mount the socket as read-only (:ro)
Use Docker's built-in authorization plugins for fine-grained access control
Keep LogDeck behind a reverse proxy with TLS in production

Permission Issues

If you encounter permission errors accessing the Docker socket, ensure the user running LogDeck has appropriate permissions:

# Check socket permissions
ls -l /var/run/docker.sock

# If needed, add user to docker group (Linux)
sudo usermod -aG docker $USER

Reverse Proxy Setup

For production deployments, it's recommended to run LogDeck behind a reverse proxy like Nginx or Traefik with TLS enabled.

Nginx Example

server {
    listen 443 ssl http2;
    server_name logdeck.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8123;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Traefik Example (Docker Labels)

services:
  logdeck:
    image: amoabakelvin/logdeck:latest
    container_name: logdeck
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /proc:/host/proc:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.logdeck.rule=Host(`logdeck.example.com`)"
      - "traefik.http.routers.logdeck.entrypoints=websecure"
      - "traefik.http.routers.logdeck.tls.certresolver=letsencrypt"
      - "traefik.http.services.logdeck.loadbalancer.server.port=8080"
    restart: unless-stopped