🚀 DockUp — Complete Docker Stack Management

DockUp is a self-hosted web interface for managing all your Docker containers and stacks. It combines visual stack management with automatic update detection, health monitoring, vulnerability scanning, a built-in Docker Registry v3, and multi-server support—all from one clean dashboard.

Think of it as your Docker control center: manage 30+ stacks across multiple servers, cache images in your private registry, schedule automatic updates like Watchtower, get notified when containers go down, and keep track of security vulnerabilities. All without touching the command line.

✨ What DockUp Does

🐳 Stack Management

Auto-Discovery & Import

Automatically finds all Docker Compose stacks in your /stacks directory
Imports standalone containers (created with docker run) and converts them to compose format
No manual setup needed—just mount your stacks folder and go

Visual Stack Editor

Edit compose files with a split-view editor that breaks services into organized sections
Separate tabs for: Basic Info, Environment Variables, Ports, Volumes, Networks, Devices, Security, and Advanced settings
Full YAML editor available if you prefer raw editing
Real-time validation catches errors before saving
Changes are saved directly to your compose files

Stack Operations

Start/Stop/Restart stacks with one click
Pull latest images to check for updates
Clone existing stacks to create duplicates
Delete stacks with optional image cleanup
Watch operations happen live with real-time terminal output
All settings and schedules survive container restarts

Smart Features

Port conflict detection warns you before starting stacks that would clash
Automatic web UI detection finds admin panels and creates clickable links
Badge system shows stack status at a glance (running, stopped, inactive, updates available)
"Fresh" indicator shows recently updated stacks

📋 Template Library

One-Click App Deployment

Browse 300+ pre-configured LinuxServer.io application templates
Each template includes optimized Docker Compose configuration
Enhanced with real-time Docker Hub metadata:
- Pull counts and star ratings
- Available image tags
- Last update timestamps
- Image sizes
Searchable by name, category, or description
Categories include: Media, Home Automation, Development, Networking, Security, and more

Smart Template System

Automatically scrapes LinuxServer.io documentation for default configurations
Generates compose files with recommended environment variables
Pre-configured volume mounts and port mappings
Health checks included where applicable
Direct links to official documentation and GitHub repos

How to Use Templates

Click "Create from Template" in dashboard
Search or browse by category
Click any template to preview its compose file
Customize stack name and settings
Deploy instantly—stack appears in dashboard
Template library refreshes automatically to stay current

🕐 Action Scheduling

Schedule Stack Actions

Schedule stacks to start, stop, or restart at specific times
Each stack supports multiple schedules (e.g., start at 8 AM, stop at 6 PM)
Uses cron expressions for flexible timing
Independent from update schedules—manage separately

Common Use Cases

Daily Restarts: Restart resource-hungry apps nightly (0 3 * * *)
Business Hours: Start stacks at 8 AM, stop at 6 PM weekdays
Weekend Shutdowns: Stop dev environments Friday evening, restart Monday morning
Periodic Refreshes: Restart every 6 hours to clear memory leaks
Maintenance Windows: Stop before backups, restart after

Schedule Configuration

Add unlimited action schedules per stack
Each schedule has:
- Action type (start, stop, restart)
- Cron expression for timing
- Optional description/label
Schedules run in your configured timezone
View upcoming scheduled actions
Enable/disable schedules without deleting them

Example Schedules

# Start at 8 AM on weekdays
0 8 * * 1-5  (start)

# Stop at 6 PM on weekdays  
0 18 * * 1-5 (stop)

# Restart every night at 3 AM
0 3 * * *    (restart)

# Restart every 6 hours
0 */6 * * *  (restart)

🌐 Multi-Server Management (Peer Mode)

Connect Multiple Servers

Link multiple DockUp installations together into one unified dashboard
See stacks from all your servers in a single view
No master/slave setup—all servers are equal peers
Secure API token authentication between instances

What You Can Do Remotely

Start, stop, and restart stacks on any connected server
Monitor CPU, RAM, and network usage across all machines
Check health status from your entire infrastructure
View which stacks are running where with server badges

What Stays Local

Editing compose files (edit directly on each server)
Viewing container logs (view on the server running them)
Configuring update schedules (each server manages its own)
Creating or deleting stacks (create on target server)

Setup is Simple

Install DockUp on each server
Give each instance a friendly name (like "Main Server" or "Media Server")
Copy the API token from the server you want to connect to
Add it as a peer connection with the server's URL
Test the connection—you're done

📊 Monitoring & Statistics

Real-Time System Stats

Host-level monitoring: CPU usage, RAM usage, disk space, network traffic
Per-stack statistics: See how much resources each stack consumes
Per-container breakdowns: CPU, memory, and network for individual containers
Configurable polling intervals to balance freshness vs system load

Polling Control DockUp gives you three independent polling settings:

Host Stats Polling: How often to refresh CPU/RAM/Disk/Network gauges (1 second to 5 minutes, or off)
Stack Refresh Polling: How often to update container status and running state (1 second to 1 hour, or off)
Health Check Polling: How often to check container health and send alerts (30 seconds to 1 hour, or off)

Set aggressive polling for real-time monitoring, or slow it way down to minimize CPU usage. Health checks run independently so you can have slow UI updates but fast failure detection.

Container Health Monitoring

Tracks which containers have health checks defined
Monitors health status continuously (healthy, unhealthy, starting)
Counts consecutive failures before alerting
Sends notifications when stacks become unhealthy
Notifies again when stacks recover
Configurable failure threshold (default: 3 failures)

Container Logs

View real-time logs for any container
Last 100 lines shown by default
Helpful for debugging startup issues or checking status

🔄 Automatic Updates (Watchtower-Style)

How Update Detection Works DockUp uses the same reliable method as Watchtower:

Records the current image IDs (digests) of your running containers
Pulls the latest versions of those images from their registries
Compares the new image IDs to the old ones
If they're different, an update is available

This method is bulletproof—it works with any Docker registry and always detects real updates.

Three Update Modes Per Stack

Off Mode

No automatic checking or updating
You manually check and update when you want

Check-Only Mode

DockUp checks for updates on your schedule
Shows "Update Available" badge on the dashboard
Sends you a notification (if enabled)
Doesn't change anything automatically
You click "Update" when ready

Auto-Update Mode

DockUp checks for updates on your schedule
When found, automatically pulls new images
Recreates containers with the new versions
Waits for containers to become healthy
Verifies containers are running new images
Sends success notification
If anything fails, sends error notification and stops

Scheduling Updates

Each stack gets its own schedule using cron expressions
Default schedule applies to new stacks (typically 2 AM daily)
Common schedules:
- 0 2 * * * = Every day at 2 AM
- 0 3 * * 0 = Every Sunday at 3 AM
- 0 4 1 * * = First of every month at 4 AM
- */30 * * * * = Every 30 minutes (for testing)
"Apply to All" button bulk-configures multiple stacks at once
Timezone-aware scheduling respects your local time

Manual Updates

Click "Check for Updates" button to check right now
Click "Update" button when available to update immediately
Watch the terminal output as it happens
Update history tracks when stacks were last updated and how (manual or automatic)

🛡️ Security Scanning with Trivy

Vulnerability Scanning

Built-in integration with Trivy (industry-standard security scanner)
Scans Docker images for known vulnerabilities (CVEs)
Shows severity levels: Critical, High, Medium, Low
Provides CVE IDs and vulnerability descriptions
Completely optional—only scans when you request it

How Scanning Works

Click "Scan" button on any stack
DockUp downloads Trivy database (first time only)
Scans all images used by that stack
Shows results grouped by severity
Results are saved and shown until next scan

Scan Results Display

Summary shows total vulnerabilities by severity
Expandable lists for each severity level
CVE details include descriptions and affected packages
Results persist across page reloads
Re-scan anytime to check if fixes are available

💾 Automated Backups

Smart Backup System DockUp includes a complete backup solution for your Docker stacks. Schedule automatic backups of your container data volumes, manage retention, and restore with a few clicks.

How Backups Work

Choose what to backup: Select which volumes from your stack to include
Set a schedule: Daily or weekly backups at a specific time
Automatic retention: Keeps your last N backups, deletes older ones
Get notified: Receive notifications when backups complete or fail

Setting Up Backups

Open any stack and go to the Backup tab. You'll see:

Schedule Settings: Choose daily or weekly backups and set the time
Volume Selection: Pick which volumes to backup (very important!)
Stop Before Backup: Option to stop containers during backup (safer but causes downtime)
Retention Count: How many backups to keep (older ones auto-delete)

⚠️ Important: Volume Selection

DockUp will show all volumes from your stack. Don't blindly backup everything!

For media apps like Radarr, Sonarr, Plex:

✅ DO backup: Config folders (databases, settings, metadata)
❌ DON'T backup: Media folders (movies, TV shows, music)

Example for Radarr:

✅ /DATA/AppData/radarr/config    ← Backup this (your settings)
❌ /media/movies                   ← Skip this (terabytes of movies)

Why? Media files are huge and don't need backing up—you can re-download them. Config folders are small but contain all your settings, which are irreplaceable.

Mass Scheduling

In the Backups tab (main dashboard), you can:

Select multiple stacks with checkboxes
Apply the same schedule to all at once
Choose whether to stop containers before backup
All stacks queue up and backup one at a time

Backup History & Restore

Each stack shows its backup history with:

Backup date and time (in your timezone)
Backup size
One-click restore button

Click Restore to roll back a stack to a previous backup. The stack will be stopped, volumes replaced, and restarted automatically.

Global Backup View

The Backups tab shows all backups across all stacks:

See every backup in one place
Restore any backup from here
Scan and import backups from other sources
Alphabetically organized by stack name

Reset Backup Config

If you accidentally selected too many volumes (like that 5TB media folder), click the red Reset Config button in the stack's Backup tab. This clears everything so you can start fresh and select only the config folders.

Storage Requirements

Backups are stored in /app/backups inside the container (mounted to $(pwd)/backups on your host). Make sure you have enough disk space for your retention policy.

Example: If you keep 7 backups of a 500MB config folder, you need about 3.5GB free space for that stack.

Moving Stacks Between Servers

DockUp's backup system works seamlessly with peer connections to migrate stacks between servers:

Backup on Source Server: Create a backup of the stack you want to move
Connect as Peers: Link your source and destination DockUp instances
Access Global Backups: From the destination server, open the Backups tab
See All Backups: You'll see backups from all connected peer servers
Restore Anywhere: Click restore on any backup to pull it to the current server
Stack Migrated: The stack is created on the new server with all data intact

This makes it easy to:

Migrate to new hardware: Move your entire setup to a new server
Balance workloads: Shift heavy stacks to more powerful machines
Test configurations: Clone production stacks to a test server
Disaster recovery: Restore from a peer if your main server fails

The backup file is transferred automatically between peers during restore—no manual file copying needed.

🖼️ Image Management

Image Overview

Lists all Docker images on your system
Alphabetically sorted with size information
Shows which images are in use by containers
Displays unused images that can be safely deleted
Storage stats help identify space hogs

Manual Cleanup

Delete individual unused images with one click
"Prune All Unused Images" removes everything not in use
Confirmation dialogs prevent accidents
Shows how much space was freed

Automatic Pruning

Schedule automatic cleanup with cron expressions
Runs in the background at your specified time
Notifications when pruning completes (optional)
Example: 0 3 * * 0 prunes unused images every Sunday at 3 AM

📦 Built-in Docker Registry v3

Complete Registry Solution DockUp includes a full Docker Registry v3 server with smart automation features. Pull images from Docker Hub once, cache them locally, and automatically keep them updated. Perfect for homelabs with multiple servers or air-gapped environments.

How It Works

Built-in Registry v3 runs on port 5500
Pull images to your local registry instead of always hitting Docker Hub
Automatically watches upstream for new versions
Updates your cached images on schedule (default: 4 AM daily)
All your servers pull from this one central cache
Faster deployments, less bandwidth usage, offline capability

Watched Images

Add any image to your watch list
DockUp monitors Docker Hub (or other registries) for updates
Compares local digest vs upstream digest
Automatically pulls new versions when available
Configurable retention policies per image:
- Latest Only: Keep only the newest version
- Keep All: Never delete old versions
- Keep N: Keep last 3, 5, 10, etc. versions

Smart Garbage Collection

Automatic cleanup of orphaned image layers
Runs once after all batch updates complete (no race conditions)
Can be triggered manually anytime
Shows space reclaimed after each run
Integrated with backup system

Registry Features

Browse all cached images in your registry
See image sizes, tags, and last updated timestamps
Add/remove images from watch list with one click
Manual pull button to cache new images immediately
View which images are being watched
See when each image was last updated
"Never" status means no upstream updates detected yet

Multi-Server Setup Perfect for distributed homelabs:

Main Server (DockUp + Registry):
├── Runs Registry on port 5500
├── Watches 48 public images
├── Auto-updates at 4 AM daily
└── Serves all other servers

Media Server (DockUp):
├── Pulls from Main Server registry
├── Faster image pulls (local network)
└── No Docker Hub rate limits

Home Assistant Server (DockUp):
├── Pulls from Main Server registry
├── Works offline
└── Consistent image versions

Backup Integration

Registry data automatically included in DockUp backups
Or use separate registry for custom images (Gitea pattern)
Restore registry from backup if needed
Watched image list preserved

Scheduled Updates

Configure check schedule per image (default: 4 AM daily)
Uses same cron format as stack schedules
Notifications when updates are found and pulled
Update history shows when images were last updated
Bulk configure multiple images at once

Registry Management

View total registry size
See how much space each image uses
One-click garbage collection
Delete specific images from registry
Clear watch list
Reset registry completely if needed

Why Use the Registry?

Speed: Pull from LAN instead of internet
Bandwidth: Download each image version once, use everywhere
Offline: Deploy containers without internet access
Consistency: All servers use same image versions
Rate Limits: Avoid Docker Hub rate limiting
Auto-Update: Images stay current automatically
Air-Gap: Perfect for isolated networks

Registry vs Docker Hub

Docker Hub: Always download from internet, rate limited, requires connectivity
DockUp Registry: Download once, cache locally, serve to all servers, work offline

Supported Registries DockUp can watch and pull from:

Docker Hub (docker.io)
GitHub Container Registry (ghcr.io)
Linux Server Container Registry (lscr.io)
Quay.io
Google Container Registry
Any Docker Registry v2/v3 compatible registry
Private registries with authentication

🌐 Network Management

View Networks

Lists all Docker networks on your system
Shows network driver type (bridge, macvlan, ipvlan, host, overlay)
Displays connected containers for each network
Subnet and gateway information visible

Create Custom Networks

Bridge networks for standard container communication
Macvlan networks for giving containers direct IPs on your LAN
Ipvlan networks for IP-level isolation
Full IPAM configuration: subnets, gateways, IP ranges
IPv4 and IPv6 support

Delete Networks

Remove unused networks safely
Warns if network is still in use
One-click deletion for empty networks

🔔 Notifications

Notification Services DockUp supports two ways to send alerts:

Gotify (Simple, Self-Hosted)

Enter your Gotify server URL
Paste your application token
Test button verifies connection
Notifications appear in your Gotify app

Apprise (80+ Services)

Supports Discord, Slack, Telegram, email, Pushover, and 75+ more
Add service URLs in Apprise format
Multiple services can be added
Test button sends to all configured services

What Gets Notified You control exactly what triggers notifications:

Update checks (Check-Only mode): When updates are detected
Completed updates (Auto mode): When auto-updates finish successfully
Errors: When operations fail (pulls, updates, health checks)
Health failures: When containers become unhealthy (after threshold)
Recovery: When previously unhealthy stacks become healthy again
Scheduled actions: When scheduled start/stop/restart actions complete
Registry updates: When watched images are updated in the registry

Health Alert Threshold

Set how many consecutive health check failures before alerting
Default: 3 failures
Prevents notification spam from brief glitches
Once threshold is reached, you get ONE notification
Another notification when stack recovers

💾 Backup & Restore

One-Click Backup

Downloads a ZIP file containing all your compose files
Includes all stack metadata and settings
Preserves update schedules and configurations
Backup includes only stacks on the current server (not remote peers)

Restore from Backup

Upload a previously downloaded backup ZIP
DockUp extracts all compose files to your stacks directory
Restores all schedules and metadata
Stacks appear immediately in the dashboard
Can restore to a different DockUp instance

What's Included in Backups

All compose.yaml / docker-compose.yml files
Stack metadata (.dockup-meta.json files)
Update schedules
Action schedules
Stack-specific settings
Health check history
Registry watched images list (if using built-in registry)

What's NOT Included

Container volumes (data inside containers)
Docker images
Global DockUp settings
Notification configurations
Peer connections
Registry image data (only watched list)

🔒 Password Protection

Completely Optional

DockUp works without a password by default
Enable authentication with a toggle switch
Disable anytime—no forced security

First-Time Setup

Enable "Password Protection" in settings
Save settings
You're redirected to create a password
Enter password twice to confirm
Automatically logged in
Password is encrypted and stored securely

Password Management

Change password anytime from settings
Sessions last 31 days (persistent across browser restarts)
bcrypt hashing (industry-standard security)
No password recovery—if forgotten, you'll need container access to reset

API Token Security

Each DockUp instance has a unique API token
Used for peer-to-peer authentication between servers
Can be regenerated if compromised
Separate from password protection
Shown only when explicitly revealed (hidden by default)

⚙️ Advanced Features

Resource Limits (Compose Editor)

Set CPU limits for services (e.g., max 2 CPU cores)
Set memory limits for services (e.g., max 2GB RAM)
Prevents runaway containers from consuming all resources
Applied via Docker Compose deploy.resources.limits

Port Conflict Detection

Warns before starting stacks with conflicting port mappings
Shows which other stack is already using a port
Prevents failed starts due to port collisions

Timezone Configuration

Set your local timezone in settings
All scheduled tasks respect your timezone
Cron schedules run at your local time, not UTC
Timestamps in UI show in your timezone

Web UI Auto-Detection

DockUp scans container ports and common paths
Automatically creates clickable links to web interfaces
Works with most common applications (Plex, Sonarr, etc.)
Saves you from memorizing port numbers

WebSocket Live Updates

Real-time terminal output during operations
Dashboard updates automatically when changes occur
No page refresh needed to see status changes
Minimal overhead—only sends updates when needed

Offline Capability

Works without internet once images are pulled
Local registries fully supported
Update detection works with air-gapped registries
Only outbound connection is for pulling images

Dark Theme

Beautiful dark interface optimized for homelabs
Easy on the eyes during late-night troubleshooting
Professional appearance
Theme preference saved per browser

🚀 Installation

⚠️ Important: Host Network Required for Registry

DockUp must run on the host network for the built-in Docker Registry to work properly. This allows the registry container to communicate with DockUp's API.

Quick Start with Docker Run

docker rm -f dockup 2>/dev/null || true \
&& docker rmi cbothma/dockup:latest 2>/dev/null || true \
&& docker pull cbothma/dockup:latest \
&& docker run -d \
  --name dockup \
  --network host \
  --privileged \
  --cap-add SYS_ADMIN \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /DATA/Compose:/stacks \
  -v /DATA/AppData:/DATA/AppData \
  -v dockup_data:/app/data \
  -v $(pwd)/backups:/app/backups \
  --restart unless-stopped \
  cbothma/dockup:latest

Note: When using --network host, the -p port mapping is not needed. DockUp will listen on port 5000 by default (or use the PORT environment variable).

Volume Explanations:

/var/run/docker.sock - Required for Docker control
/DATA/Compose:/stacks - Your Docker Compose stacks directory
/DATA/AppData:/DATA/AppData - Container data for size calculation and backups
dockup_data:/app/data - DockUp's settings and database
$(pwd)/backups:/app/backups - Backup storage location

Optional PORT environment variable:

docker run -d \
  --name dockup \
  --network host \
  -e PORT=8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/your/stacks:/stacks \
  -v dockup_data:/app/data \
  --restart unless-stopped \
  cbothma/dockup:latest

Docker Compose

version: '3.8'
services:
  dockup:
    image: cbothma/dockup:latest
    container_name: dockup
    network_mode: host
    privileged: true
    cap_add:
      - SYS_ADMIN
    environment:
      - PORT=5000  # Optional: change DockUp's port (default: 5000)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /path/to/your/stacks:/stacks
      - /path/to/appdata:/DATA/AppData  # For backup size calculations
      - dockup_data:/app/data
      - ./backups:/app/backups
    restart: unless-stopped

volumes:
  dockup_data:

Important Notes:

network_mode: host is required for the built-in registry to work
When using host network, remove the ports: section
DockUp will be accessible on http://your-server-ip:5000 (or your custom PORT)
The built-in registry will be accessible on http://your-server-ip:5500

What Each Mount Does

Volume	Purpose	Required
`/var/run/docker.sock`	Docker API access—lets DockUp control containers	Yes
`/stacks`	Your compose files directory—where your stacks live	Yes
`/app/data`	Settings, schedules, metadata, tokens—everything DockUp remembers	Yes
`/DATA/AppData`	Access to container data for backup size calculations	Recommended
`/app/backups`	Stack backup storage location	Recommended

Important Notes:

The /stacks directory is where DockUp looks for compose files
Each subdirectory in /stacks becomes one stack
Each subdirectory needs a compose.yaml (or docker-compose.yml) file
The /app/data volume must persist—losing it means losing all your settings
The PORT environment variable allows running DockUp on any port (default: 5000)
Host network mode is required for the built-in Docker Registry v3 to function

🎯 Getting Started

First Login

Open browser to http://localhost:5000 (or your server's IP)
Dashboard loads immediately—no password required by default
If you want password protection, go to Settings and enable it
Otherwise, you're ready to go

Registry Tab

Accessing the Registry

Click the "Registry" tab in the main navigation
See all images currently cached in your local registry
View image sizes, tags, and last updated timestamps
"Never" means the image was pulled but no upstream updates detected yet

Adding Images to Watch

Click "Add Image" button
Enter image name (e.g., linuxserver/plex or nginx:alpine)
Choose retention policy:
- Latest Only: Keep only newest version
- Keep All: Never delete old versions
- Keep Last 3/5/10: Keep N most recent versions
Click Add—image is pulled and added to watch list

Configuring Registry Updates

Each watched image has its own schedule
Default: 4 AM daily (0 4 * * *)
Click schedule icon to customize
Notifications sent when updates are found and pulled

Using Your Registry Point your stacks to use your local registry:

services:
  plex:
    image: localhost:5500/linuxserver/plex:latest

Or configure other servers to pull from your registry:

services:
  sonarr:
    image: 192.168.1.100:5500/linuxserver/sonarr:latest

Managing Registry

Click "Run GC" to reclaim space from deleted images
View space reclaimed after garbage collection
Delete individual images from watch list
Pull updates manually with "Pull Now" button

Your First Stack

Method 1: Create from Template

Click "Create from Template" button
Browse or search the template library
Click any template to see details and preview compose file
Click "Use Template" button
Customize stack name if desired
Stack is created and appears in dashboard
Click "Start" to launch the application

Method 2: Create New Stack

Click "Create Stack" button
Enter a stack name (lowercase, no spaces)
Choose "Split Editor" or "YAML Editor"
Add your services, ports, volumes
Save—stack appears in dashboard

Method 3: Import Existing

Copy your compose files into the /stacks directory
Create one folder per stack
Put compose.yaml inside each folder
Refresh DockUp—stacks appear automatically

Method 4: Import Running Containers

DockUp automatically detects standalone containers (created with docker run)
They appear in the dashboard with an "Import" button
Click Import to convert them to compose format
Original containers keep running—nothing is disrupted

Managing Your Stacks

Starting and Stopping

Green "Start" button starts all services in a stack
Red "Stop" button stops and removes containers (data in volumes is safe)
Yellow "Restart" button restarts all containers in the stack
Blue "Pull" button downloads latest images without restarting

Checking for Updates

Click "Check for Updates" button on any stack
DockUp pulls latest images and compares them
If updates found, orange "Update" button appears
Click "Update" to pull images and recreate containers
Watch progress in the real-time terminal window

Setting Up Auto-Updates

Click the schedule icon next to any stack
Choose a mode:
- Check Only: Get notified, update manually
- Auto Update: Automatic pull and restart
Set schedule (or use default 2 AM daily)
Save—DockUp handles updates from now on

Scheduling Actions (Start/Stop/Restart)

Click the schedule icon next to any stack
Go to "Action Schedules" tab
Click "Add Schedule"
Choose action type: Start, Stop, or Restart
Enter cron expression (e.g., 0 8 * * 1-5 for 8 AM weekdays)
Add optional description
Save—action runs automatically on schedule

Common Action Schedule Examples:

Start at 8 AM weekdays: 0 8 * * 1-5 (start)
Stop at 6 PM weekdays: 0 18 * * 1-5 (stop)
Restart every night: 0 3 * * * (restart)
Restart every 6 hours: 0 */6 * * * (restart)

Editing Compose Files

Click "Edit" button on any stack
Split Editor shows organized sections, or use YAML Editor for raw editing
Make your changes
Click "Save"
Changes written immediately to compose file
Restart stack to apply changes

Configuring Notifications

Gotify Setup:

Settings → Notifications
Enter Gotify URL: http://your-gotify:8080
Enter Application Token (create in Gotify first)
Click "Test Gotify"—you should get a notification
Enable the alert types you want
Save Settings

Apprise Setup (Discord Example):

Create Discord webhook in your server settings
Copy webhook URL
In DockUp Settings → Notifications
Click "Add Apprise URL"
Paste: discord://webhook_id/webhook_token
Click "Test Apprise"—message appears in Discord
Save Settings

Setting Up Multi-Server (Peer Mode)

On Server 1 (e.g., Main Server):

Settings → Remote DockUp Instances
Set Instance Name: "Main Server"
Copy the API Token (click eye icon, then copy)

On Server 2 (e.g., Media Server):

Install DockUp same way as Server 1
Settings → Remote DockUp Instances
Set Instance Name: "Media Server"
In "Connected Peers" section, click "Add Remote Instance"
Fill in:
- Instance ID: main-server
- Display Name: Main Server
- URL: http://192.168.1.100:5000
- API Token: (paste from Server 1)
Click "Add Peer"
Click "Test"—should connect successfully
Return to Dashboard—you'll now see stacks from both servers

Backing Up Your Setup

Settings → scroll to Backup section
Click "Backup All Stacks"
Downloads a ZIP file with everything
Store it somewhere safe
To restore: click "Restore from Backup" and select the ZIP

Understanding the Dashboard

Stack Cards Show:

Stack name and running status
Server badge (if from a peer)
Container count and health status
CPU, RAM, and network usage
Update available badge (orange)
Fresh badge (green, if updated in last 24 hours)
Action buttons (Start/Stop/Restart/Edit/etc.)

Color Meanings:

Green: Running and healthy
Red: Stopped or has stopped containers
Yellow: Some containers stopped (partial)
Gray: Never started (inactive)
Orange: Update available

Collapsible Sections:

Click stack card to expand/collapse details
Shows individual containers with their stats
Container-level health indicators
Quick access to container logs

⚙️ Configuration Guide

All settings are managed through the web interface. Everything you configure is stored persistently and survives container restarts.

Polling Intervals

Control how often DockUp checks various things:

Host Stats Polling

How often to refresh CPU/RAM/Disk/Network gauges
Options: Off, 1s, 5s, 15s, 30s, 60s, 5min
High frequency = smoother graphs, more CPU usage
Low frequency = less smooth, lower CPU usage
Recommended: 30 seconds for normal use

Stack Refresh Polling

How often to update container status and running state
Options: Off, 1s, 5s, 15s, 30s, 1min, 5min, 10min, 30min, 1 hour
Affects how quickly dashboard shows state changes
Set higher (10-30 min) if you have many stacks to reduce overhead
Recommended: 1 minute for active monitoring, 10+ minutes for large deployments

Health Check Polling

How often to check container health and trigger alerts
Options: Off, 30s, 1min, 2min, 5min, 10min, 15min, 30min, 1 hour
Runs independently of other polling
Fast health checks mean faster failure detection
Slower checks mean less system overhead
Recommended: 5 minutes (good balance of speed and efficiency)

Notification Settings

Service Configuration

Gotify URL and Token for Gotify notifications
Apprise URLs for everything else (Discord, Slack, email, etc.)
Test buttons verify connectivity

Alert Toggles

Notify on update checks (Check-Only mode)
Notify on completed updates (Auto mode)
Notify on errors (failed operations)
Notify on health failures (after threshold reached)
Notify on scheduled actions (when start/stop/restart completes)
Notify on registry updates (when watched images are updated)

Health Check Threshold

How many consecutive failures before sending alert
Default: 3
Range: 1-10
Lower = more sensitive, more notifications
Higher = fewer false alarms, slower detection

Timezone

Set your local timezone for accurate scheduling
All cron schedules run in this timezone
All timestamps display in this timezone
Dropdown shows all standard timezones

Auto-Prune Images

Enable automatic cleanup of unused Docker images
Set schedule with cron expression
Example: 0 3 * * 0 = Every Sunday at 3 AM
Frees disk space automatically
Notification sent when pruning completes (optional)

Password Protection

Toggle to enable/disable authentication
When enabled, redirects to password setup if not set
When disabled, anyone can access (default)
Change password button when enabled
No password recovery—container access required to reset

Remote DockUp Instances (Peer Mode)

This Instance Section:

Set Instance Name (how this server identifies itself)
View and copy API Token
Regenerate token if compromised

Connected Peers Section:

Add new peer connections
Test existing connections
Edit peer URLs or tokens
Remove peers
Enable/disable individual peers

Template Library Settings

Enable/Disable Templates

Toggle template library on/off
When disabled, "Create from Template" button hidden
Existing stacks unaffected

Refresh Templates

Manual refresh button to update template library
Fetches latest LinuxServer.io templates
Updates Docker Hub metadata (pulls, stars, descriptions)
Re-scrapes documentation for current configs
Cache refreshes automatically every 7 days

Registry Settings

Enable/Disable Registry

Toggle built-in Docker Registry on/off
When disabled, Registry tab is hidden
Existing watched images preserved

Default Update Schedule

Set default cron schedule for newly watched images
Example: 0 4 * * * = Every day at 4 AM
Individual images can override this

Notification Preferences

Notify when registry updates are pulled
Notify on registry errors
Included in general notification settings

🔧 How It Works

Update Detection Process

DockUp uses the Watchtower method because it's the most reliable:

Record Current State: Reads image ID (digest) from each running container
Pull Latest: Pulls latest version of each image from its registry
Compare IDs: Checks if new image ID differs from old ID
Report: If different, update is available

This works with:

DockerHub
GitHub Container Registry (ghcr.io)
Linux Server Container Registry (lscr.io)
Quay.io
Google Container Registry
Private registries
Local registries (including DockUp's built-in registry)
Any Docker Registry v2/v3 compatible registry

Registry Update Process

When the scheduled time arrives for registry checks:

Check Each Watched Image: For every image in the watch list
Query Upstream: Contact Docker Hub (or other registry) for latest digest
Compare Digests: Check if upstream digest differs from local
Pull If Different: Download new version to local registry
Apply Retention: Delete old versions based on retention policy
Run GC: Garbage collect orphaned layers (once after all updates)
Notify: Send notification of what was updated
Update Status: Mark image as updated with timestamp

Auto-Update Process (Auto Mode)

When scheduled time arrives and update is detected:

Pull Images: Downloads latest versions of all images in stack
Compare: Verifies new images are actually different
Stop Containers: Gracefully stops current containers
Create New: Starts new containers with updated images
Wait: Allows time for startup (10 seconds)
Verify Health: Checks container health status
Confirm: Verifies new image IDs match pulled versions
Notify: Sends success or failure notification

If any step fails, the process stops and an error notification is sent.

Action Scheduling Process

When a scheduled action (start/stop/restart) is triggered:

Execute Action: Runs the scheduled operation (start, stop, or restart)
Verify Status: Checks that the operation completed successfully
Notify: Sends notification if enabled (success or failure)
Log History: Records the scheduled action in stack history

Multiple schedules can exist for the same stack, allowing complex automation patterns like:

Start stack every weekday morning
Stop stack every weekday evening
Restart stack nightly for memory cleanup

Health Monitoring

DockUp checks container health by:

Reading container's health status from Docker API
Health status can be: healthy, unhealthy, starting, or none (no health check)
Tracking consecutive failures per stack
Comparing against configured threshold (default: 3)
Sending notification once threshold reached
Resetting counter when stack becomes healthy
Sending recovery notification when previously failed stack recovers

Containers without health checks defined show "none" status and don't trigger alerts.

Template System

The template library works by:

Fetching Templates: Pulls LinuxServer.io repository list from GitHub API
Docker Hub Integration: Fetches metadata for each image (pulls, stars, tags, size)
Documentation Scraping: Scrapes LinuxServer.io docs for recommended configurations
Compose Generation: Creates optimized compose files with:
- Recommended environment variables from docs
- Pre-configured volume mounts
- Correct port mappings
- Health checks where applicable
Caching: Stores templates locally to reduce API calls
Auto-Refresh: Updates cache every 7 days or on manual refresh

Peer Communication

When you connect DockUp instances as peers:

Authentication: Each request includes API token in header
Session Caching: Successful auth cached to reduce overhead
Stack List: Primary instance requests /api/stacks/all from peer
Status Sync: Peer returns full stack list with current status
Operations: Primary proxies operations to peer via /api/peer/{id}/stack/{name}/operation
Read-Only: Destructive operations (edit, delete) disabled for remote stacks

Each instance remains independent—peer connections only provide read/control access, not synchronization.

Registry Architecture

DockUp's built-in registry consists of:

Registry Container: Standard Docker Registry v3 running on port 5500
Registry Manager: Python module that wraps the registry with automation
Watch Scheduler: Cron-based system that checks for upstream updates
GC Orchestrator: Manages garbage collection after batch updates
Retention Engine: Applies version retention policies per image

The registry runs as a separate container managed by DockUp, communicating via the Docker socket and DockUp's API.

Data Persistence

DockUp stores all configuration in the /app/data volume:

Settings: Timezone, notification configs, polling intervals
Schedules: Per-stack update schedules and modes
Action Schedules: Per-stack start/stop/restart schedules
Backup Configs: Backup schedules, volume selections, retention settings
Backup History: Backup timestamps, sizes, and metadata
Update Status: Last check time, update available flags
Update History: When stacks were updated and by whom
Health Status: Consecutive failure counts, last notification time
Peer Connections: Remote instance URLs and tokens
Passwords: Encrypted password hashes (if enabled)
API Token: This instance's authentication token
Scan Results: Trivy vulnerability scan data
Template Cache: LinuxServer.io templates and metadata
Registry Data: Watched images list, retention policies, update schedules

Registry image data is stored separately in the registry container's volume.

Backups themselves are stored in /app/backups (separate volume mount recommended).

If the /app/data volume is lost, all settings reset to defaults but your compose files (in /stacks) are unaffected.

Orphan Container Import

When DockUp finds containers not managed by any compose file:

Reads container's labels, environment variables, ports, volumes
Generates equivalent compose YAML
Creates new stack directory in /stacks
Writes compose.yaml with container's configuration
Adds metadata file
Original container keeps running—nothing is modified

You can then manage the container through DockUp like any other stack.

🛠️ Troubleshooting

DockUp Won't Start

Check Docker Socket

ls -l /var/run/docker.sock

Must be readable by container. If not, check volume mount.

Check Host Network

docker inspect dockup | grep NetworkMode

Should show "NetworkMode": "host". If not, recreate with --network host.

Check Logs

docker logs dockup

Look for startup errors or permission issues.

Registry Not Working

Verify Host Network Registry requires host network mode to communicate with DockUp:

docker inspect dockup | grep NetworkMode

Should be "host". Recreate container with --network host if not.

Check Registry Container

docker ps | grep registry

Should show a registry container running on port 5500.

Test Registry Connectivity

curl http://localhost:5500/v2/

Should return {}. If not, check firewall or registry logs.

Check Registry Logs

docker logs dockup-registry

Look for startup errors or permission issues.

Auto-Updates Not Running

Verify Schedule Configuration

Open stack schedule settings
Ensure mode is "Check" or "Auto" (not "Off")
Verify cron expression is valid
Check timezone setting matches your location

Check Logs for Scheduler

docker logs dockup | grep -i "scheduled\|update check"

Should see: Scheduled update check for <stack>: 0 2 * * *

Test with Frequent Schedule

Set cron to */2 * * * * (every 2 minutes)
Watch logs for execution
Change back to normal schedule after testing

Registry Updates Not Running

Check Registry Tab

Open Registry tab
Verify images are in watch list
Check each image has a schedule configured

Check Logs

docker logs dockup | grep -i "registry\|watch"

Look for scheduled registry checks and update messages.

Test Manual Update

Click "Pull Now" on a watched image
Should see pull progress and notification
Check "Last Updated" timestamp changes

Action Schedules Not Running

Verify Action Schedule Configuration

Open stack schedule settings
Go to "Action Schedules" tab
Ensure schedules are present and have valid cron expressions
Check timezone setting

Check Logs for Scheduled Actions

docker logs dockup | grep -i "schedule.*action\|scheduled.*start\|scheduled.*stop\|scheduled.*restart"

Should see: [Schedule] Running start for <stack>

Notifications Not Arriving

Test Connection

Settings → Notifications
Click "Test Gotify" or "Test Apprise"
Check for error messages

Verify Service URLs

Gotify: Check URL format and token
Apprise: Verify service URL format
Ensure services are reachable from DockUp container

Check Alert Toggles

Ensure relevant notification types are enabled
Remember: health alerts only trigger after threshold failures

High CPU Usage

Check Polling Intervals

Settings → Polling Intervals
Reduce Host Stats Polling (try 30 seconds)
Reduce Stack Refresh Polling (try 10 minutes)
Health Check Polling can be 5-10 minutes

Check Container Count

More containers = more overhead
Each container is polled individually
Consider grouping services into fewer stacks

Check Logs for Errors

docker logs dockup | tail -100

Look for repeated error messages that might cause retry loops.

Peer Connection Fails

Test Connectivity

curl http://peer-server:5000/api/peer/test

Should return JSON response.

Verify API Token

Copy token again from peer's settings
Ensure no extra spaces or truncation
Paste carefully when adding peer

Check Firewall

Ensure port 5000 (or your port) is open
Check both server and network firewalls
Try from DockUp container: docker exec -it dockup curl http://peer:5000

Stack Won't Start

Check Port Conflicts

DockUp shows port conflict warnings
Another container or service might be using the port
Change port in compose file or stop conflicting service

Check Logs

Click "Logs" button on stack
Look for error messages from containers
Common issues: missing volumes, bad env vars, wrong image tags

Try Manual Start

cd /path/to/stacks/stackname
docker compose up -d

Error messages show exact problem.

Templates Not Loading

Check Template Library Setting

Settings → scroll to Template Library
Ensure templates are enabled
Try manual refresh button

Check Network Access

DockUp needs internet to fetch templates
Verify connection: docker exec -it dockup curl https://api.github.com
Check firewall/proxy settings

Check Logs

docker logs dockup | grep -i template

Look for template fetching errors.

Lost Password

If you forget your password and have container access:

# Option 1: Disable password protection
docker exec -it dockup python3 -c "
import json
with open('/app/data/config.json', 'r') as f:
    config = json.load(f)
config['password_enabled'] = False
with open('/app/data/config.json', 'w') as f:
    json.dump(config, f, indent=2)
"

# Option 2: Delete password hash
docker exec -it dockup rm /app/data/password.hash

# Then restart DockUp
docker restart dockup

Scan Results Not Showing

Check Trivy Installation

docker exec -it dockup trivy --version

Should show Trivy version.

Check Cache Directory

docker exec -it dockup ls -la /app/data/trivy-cache

Should exist and be writable.

Manual Scan Test

docker exec -it dockup trivy image --cache-dir /app/data/trivy-cache nginx:latest

Should download database and show results.

Backups Not Running

Check Backup Schedule

Open stack → Backup tab
Ensure backup is enabled and scheduled (not "Manual")
Verify time and day settings
Check timezone in Settings matches your location

Check Logs

docker logs dockup | grep -i backup

Look for backup queue messages and completion notifications.

Check Storage Space

df -h $(pwd)/backups

Ensure enough free space for your retention policy.

Test Manual Backup

Open stack → Backup tab
Click "Backup Now"
Watch for notification
Check backup appears in history

Reset Backup Config If backups aren't working or you selected wrong volumes:

Open stack → Backup tab
Click red "Reset Config" button
Reconfigure from scratch
Select only config folders (not media!)

📜 License

MIT License — Free to use, modify, and share.

🙏 Credits

Built with inspiration from:

Dockge — Clean stack management interface
Watchtower — Reliable auto-update methodology
Portainer — Comprehensive Docker management
Trivy — Industry-standard vulnerability scanning
LinuxServer.io — Excellent container templates and documentation
Docker Distribution — Docker Registry v3 implementation
Created with the assistance of AI.

DockUp aims to be lightweight, focused, and genuinely useful for homelabs and small deployments.

Simple. Powerful. Multi-Server. Registry-Enabled. Just Works. 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 486 Commits
.gitea/workflows		.gitea/workflows
dockup		dockup
docs		docs
CHANELOG.md		CHANELOG.md
LICENSE		LICENSE
README.md		README.md
dockup-demo.gif		dockup-demo.gif
renovate.json		renovate.json

Folders and files

Latest commit

History

Repository files navigation

🚀 DockUp — Complete Docker Stack Management

✨ What DockUp Does

🐳 Stack Management

📋 Template Library

🕐 Action Scheduling

🌐 Multi-Server Management (Peer Mode)

📊 Monitoring & Statistics

🔄 Automatic Updates (Watchtower-Style)

🛡️ Security Scanning with Trivy

💾 Automated Backups

🖼️ Image Management

📦 Built-in Docker Registry v3

🌐 Network Management

🔔 Notifications

💾 Backup & Restore

🔒 Password Protection

⚙️ Advanced Features

🚀 Installation

Quick Start with Docker Run

Docker Compose

What Each Mount Does

🎯 Getting Started

First Login

Registry Tab

Your First Stack

Managing Your Stacks

Configuring Notifications

Setting Up Multi-Server (Peer Mode)

Backing Up Your Setup

Understanding the Dashboard

⚙️ Configuration Guide

Polling Intervals

Notification Settings

Timezone

Auto-Prune Images

Password Protection

Remote DockUp Instances (Peer Mode)

Template Library Settings

Registry Settings

🔧 How It Works

Update Detection Process

Registry Update Process

Auto-Update Process (Auto Mode)

Action Scheduling Process

Health Monitoring

Template System

Peer Communication

Registry Architecture

Data Persistence

Orphan Container Import

🛠️ Troubleshooting

DockUp Won't Start

Registry Not Working

Auto-Updates Not Running

Registry Updates Not Running

Action Schedules Not Running

Notifications Not Arriving

High CPU Usage

Peer Connection Fails

Stack Won't Start

Templates Not Loading

Lost Password

Scan Results Not Showing

Backups Not Running

📜 License

🙏 Credits

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages