Skip to main content

Deploy Pluton with Docker

This guide walks you through deploying Pluton using Docker and Docker Compose for a production-ready backup server.

Quick Start​

1. Create Docker Compose File​

Create docker-compose.yml:

version: "3.8"

services:
  pluton:
    image: plutonhq/pluton:latest
    container_name: pluton
    restart: unless-stopped
    ports:
      - "5173:5173" # Web UI
      - "1883:1883" # MQTT for remote agents
    environment:
      - USER_NAME=admin
      - USER_PASSWORD=ChangeThisPassword123!
      - SECRET=your-secret-key-change-this
      - ENCRYPTION_KEY=your-encryption-key-change-this
      - APP_URL=http://localhost:5173
      - SERVER_PORT=5173
      - MQTT_PORT=1883
    volumes:
      - pluton-data:/app/data
      - pluton-backups:/backups
      # Mount additional volumes for backup sources
      # - /path/on/host:/path/in/container:ro
    networks:
      - pluton-network

volumes:
  pluton-data:
    driver: local
  pluton-backups:
    driver: local

networks:
  pluton-network:
    driver: bridge

2. Configure Environment Variables​

Create a .env file in the same directory for easier management:

# Authentication
USER_NAME=admin
USER_PASSWORD=ChangeThisPassword123!

# Security Keys (generate unique values)
SECRET=generate-a-random-secret-key-here
ENCRYPTION_KEY=generate-a-random-encryption-key

# Application URLs
APP_URL=http://localhost:5173
SERVER_PORT=5173
MQTT_PORT=1883

# Optional Settings
ALLOW_CUSTOM_RESTORE_PATH=true
ALLOW_FILE_BROWSER=true
DISABLE_EVENT_SCRIPTS=false

Generate secure keys:

# Generate SECRET
openssl rand -base64 32

# Generate ENCRYPTION_KEY
openssl rand -base64 32

Update your docker-compose.yml to use the .env file:

services:
  pluton:
    image: plutonhq/pluton:latest
    # ... other settings
    env_file:
      - .env
    # Remove or comment out the environment: section

3. Start Pluton​

docker compose up -d

4. Access Pluton​

Open your browser and navigate to:

http://localhost:5173

Login with:

  • Username: admin (or your configured USER_NAME)
  • Password: Your configured USER_PASSWORD

Configuration Details​

Environment Variables​

VariableRequiredDefaultDescription
USER_NAMEYesadminInitial admin username
USER_PASSWORDYes-Initial admin password (min 8 chars)
SECRETYes-JWT token secret key
ENCRYPTION_KEYYes-Backup encryption master key
APP_URLNohttp://localhost:5173Public URL for the application
SERVER_PORTNo5173Port for the web server
MQTT_PORTNo1883Port for MQTT broker (remote agents)
ALLOW_CUSTOM_RESTORE_PATHNotrueAllow custom restore locations
ALLOW_FILE_BROWSERNotrueEnable file browser for path selection
DISABLE_EVENT_SCRIPTSNofalseDisable pre/post backup scripts

Security Notes:

  • Never use default passwords in production
  • Generate unique SECRET and ENCRYPTION_KEY
  • Keep ENCRYPTION_KEY safe - without it, encrypted backups cannot be restored
  • Store keys securely (password manager, vault)

Volume Mounts​

Required Volumes​

Application Data (pluton-data)

volumes:
  - pluton-data:/app/data

Stores:

  • SQLite database
  • Application logs
  • Configuration files
  • Backup metadata
  • Temporary files

Backup Storage (pluton-backups)

volumes:
  - pluton-backups:/backups

Default location for local storage backups.

Mounting Source Directories​

To backup data from the host machine, mount directories into the container:

volumes:
  # Mount host directory (read-only recommended)
  - /home/user/documents:/mnt/documents:ro
  - /var/www/html:/mnt/websites:ro
  - /etc:/mnt/configs:ro

  # Mount with read-write if needed
  - /data/media:/mnt/media:rw

Access in Pluton:

  • Navigate to mounted paths when creating backup plans
  • Example: Select /mnt/documents as source path

Best Practices:

  • Use :ro (read-only) when possible for safety
  • Mount specific directories, not entire filesystems
  • Use descriptive mount point names (/mnt/descriptive-name)

External Storage Volumes​

Mount external drives or network shares:

volumes:
  # External USB drive
  - /media/external-drive:/mnt/external:rw

  # NAS mount
  - /mnt/nas/backups:/mnt/nas-backups:rw

  # Network share (ensure mounted on host first)
  - /mnt/network-share:/mnt/network:rw

Networking​

Default Configuration​

networks:
  pluton-network:
    driver: bridge

Pluton runs on an isolated network with exposed ports.

Exposed Ports​

Port 5173 (Web UI)

  • Access the Pluton dashboard
  • REST API endpoints
  • WebSocket connections

Port 1883 (MQTT)

  • Communication with remote Pluton agents
  • Device synchronization
  • Real-time status updates

Custom Port Mapping​

Change host ports while keeping container ports the same:

ports:
  - "8080:5173" # Access UI at http://localhost:8080
  - "1884:1883" # MQTT on host port 1884

Update APP_URL accordingly:

environment:
  - APP_URL=http://localhost:8080

Reverse Proxy Setup​

For HTTPS and custom domains, use a reverse proxy (nginx, Traefik, Caddy).

Example nginx configuration:

server {
    listen 80;
    server_name backup.yourdomain.com;

    location / {
        proxy_pass http://localhost:5173;
        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;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Update environment:

environment:
  - APP_URL=https://backup.yourdomain.com

Production Deployment​

Complete docker-compose.yml Example​

version: "3.8"

services:
  pluton:
    image: plutonhq/pluton:latest
    container_name: pluton
    restart: unless-stopped

    ports:
      - "5173:5173"
      - "1883:1883"

    env_file:
      - .env

    volumes:
      # Application data
      - pluton-data:/app/data

      # Backup storage
      - pluton-backups:/backups

      # Source directories to backup (examples)
      - /var/www:/mnt/www:ro
      - /home:/mnt/home:ro
      - /etc:/mnt/configs:ro

      # External backup destination
      - /mnt/backup-drive:/mnt/external-backup:rw

    networks:
      - pluton-network

    # Resource limits (optional)
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4G
        reservations:
          cpus: "1.0"
          memory: 2G

    # Health check
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5173/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  pluton-data:
    driver: local
  pluton-backups:
    driver: local

networks:
  pluton-network:
    driver: bridge

Resource Management​

CPU Limits:

deploy:
  resources:
    limits:
      cpus: "2.0" # Maximum 2 CPU cores

Memory Limits:

deploy:
  resources:
    limits:
      memory: 4G # Maximum 4GB RAM

Adjust based on:

  • Backup frequency and size
  • Number of concurrent backups
  • Available system resources

Container Management​

Start Pluton​

docker compose up -d

Stop Pluton​

docker compose down

Restart Pluton​

docker compose restart

View Logs​

# Follow logs in real-time
docker compose logs -f

# Last 100 lines
docker compose logs --tail=100

# Specific service logs
docker logs pluton -f

Update Pluton​

# Pull latest image
docker compose pull

# Recreate container with new image
docker compose up -d

Check Status​

# Container status
docker compose ps

# Resource usage
docker stats pluton

Data Persistence​

Backup Pluton Data​

Option 1: Volume Backup

# Stop Pluton
docker compose down

# Backup volumes
docker run --rm \
  -v pluton-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/pluton-data-backup.tar.gz -C /data .

docker run --rm \
  -v pluton-backups:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/pluton-backups-backup.tar.gz -C /data .

# Restart Pluton
docker compose up -d

Option 2: Direct Volume Access

# Find volume location
docker volume inspect pluton-data

# Copy data directory
sudo cp -r /var/lib/docker/volumes/pluton-data/_data /backup/location/

Restore Pluton Data​

# Stop Pluton
docker compose down

# Restore volume
docker run --rm \
  -v pluton-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/pluton-data-backup.tar.gz -C /data"

# Restart Pluton
docker compose up -d

Troubleshooting​

Container Won't Start​

Check logs:

docker compose logs pluton

Common issues:

  • Port already in use (change host ports)
  • Invalid environment variables
  • Insufficient permissions on volumes
  • Low disk space

Cannot Access Web UI​

Verify container is running:

docker compose ps

Check port mapping:

docker port pluton

Test connectivity:

curl http://localhost:5173/api/health

Permission Issues​

Container runs as specific user:

services:
  pluton:
    user: "1000:1000" # Match your host user ID

Fix volume permissions:

# Find volume location
docker volume inspect pluton-data

# Fix ownership (adjust UID/GID as needed)
sudo chown -R 1000:1000 /var/lib/docker/volumes/pluton-data/_data

High Resource Usage​

Check container stats:

docker stats pluton

Reduce concurrent backups:

  • Adjust backup schedules to avoid overlap
  • Increase retry delays
  • Reduce performance settings in plan configuration

Set resource limits:

deploy:
  resources:
    limits:
      cpus: "1.0"
      memory: 2G

Database Issues​

Access SQLite database:

docker exec -it pluton sqlite3 /app/data/db/pluton.db

Backup database:

docker exec pluton sqlite3 /app/data/db/pluton.db ".backup '/app/data/db/backup.db'"

Security Best Practices​

Network Security​

  1. Use firewall rules to restrict access to ports 5173 and 1883
  2. Deploy behind reverse proxy with HTTPS/SSL
  3. Use private networks for multi-container setups
  4. Enable authentication on MQTT if exposing remotely

Data Security​

  1. Enable backup encryption for all plans
  2. Store ENCRYPTION_KEY securely - loss means data loss
  3. Use strong passwords (min 12 characters)
  4. Rotate credentials periodically
  5. Mount source volumes read-only when possible

Container Security​

  1. Keep image updated - pull latest regularly
  2. Run as non-root user when possible
  3. Limit container resources to prevent DoS
  4. Scan images for vulnerabilities
  5. Use secrets management for sensitive data

Advanced Configuration​

Using Docker Secrets​

services:
  pluton:
    image: plutonhq/pluton:latest
    secrets:
      - db_password
      - encryption_key
    environment:
      - USER_PASSWORD_FILE=/run/secrets/db_password
      - ENCRYPTION_KEY_FILE=/run/secrets/encryption_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  encryption_key:
    file: ./secrets/encryption_key.txt

Running Behind Traefik​

services:
  pluton:
    image: plutonhq/pluton:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.pluton.rule=Host(`backup.yourdomain.com`)"
      - "traefik.http.routers.pluton.entrypoints=websecure"
      - "traefik.http.routers.pluton.tls.certresolver=letsencrypt"
      - "traefik.http.services.pluton.loadbalancer.server.port=5173"
    networks:
      - traefik-network
      - pluton-network

Custom Health Check​

healthcheck:
  test: ["CMD-SHELL", "curl -f http://localhost:5173/api/health || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 60s

Migration from Standalone​

Export from Standalone Installation​

  1. Stop Pluton service
  2. Backup data directory (usually /path/to/pluton/data)
  3. Note your configuration settings

Import to Docker​

  1. Create volume mount for data:
volumes:
  - /path/to/pluton/data:/app/data
  1. Use same environment variables
  2. Start Docker container
  3. Verify data integrity

Multi-Architecture Support​

Pluton Docker images support multiple architectures:

  • linux/amd64 (x86_64)
  • linux/arm64 (ARM64/aarch64)
  • linux/arm/v7 (ARMv7)

Docker automatically pulls the correct image for your platform.

Useful Commands​

# View container details
docker inspect pluton

# Execute commands in container
docker exec -it pluton sh

# Copy files from container
docker cp pluton:/app/data/logs ./logs

# Copy files to container
docker cp ./config.json pluton:/app/data/

# View container processes
docker top pluton

# View container resource usage
docker stats pluton --no-stream

Getting Help​

If you encounter issues:

  1. Check logs: docker compose logs -f pluton
  2. Verify configuration: Review environment variables and volumes
  3. Check disk space: df -h
  4. Review documentation: Pluton Docs
  5. Community support: Forum
  6. Report issues: GitHub Issues

Quick Reference​

# Start
docker compose up -d

# Stop
docker compose down

# Restart
docker compose restart

# Logs
docker compose logs -f

# Update
docker compose pull && docker compose up -d

# Backup data
docker run --rm -v pluton-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/pluton-backup.tar.gz -C /data .

# Check status
docker compose ps

# Shell access
docker exec -it pluton sh