Automated cPanel backup
management

Configuration

All settings live in one JSON file, ftp_config.json (mounted read-only at /app/ftp_config.json in Docker). Each top-level key other than notifications is a host; the key (cpanel1, website, …) is the name used in the web UI, the CLI and the API.

{
  "notifications": { ... },
  "cpanel1": {
    "host": "ftp.example.com",
    "ftp_username": "backup@example.com",
    "ftp_password": "your-ftp-password",
    "cpanel_username": "exampleuser",
    "cpanel_api_token": "YOUR_TOKEN",
    "backup_local_dest_folder": "/backups",
    "mail_to_notify": "you@example.com",
    "time_to_wait": 60,
    "retention_days": 30,
    "schedule": "0 2 * * *"
  }
}

Archives are stored as <backup_local_dest_folder>/<domain>/backup-*.tar.gz, where the domain is host without the ftp. prefix.

Host fields

Generating a cPanel API token

1. Log in to cPanel and open Manage API Tokens.
2. Create a token with a descriptive name (e.g. cpanelvault).
3. Paste its value into cpanel_api_token.

Environment variables

Defaults shown are the ones set in the Docker image; outside Docker, CONFIG_FILE and STATUS_FILE default to ftp_config.json and status.json in the working directory.

Notifications

Channels are configured in the notifications key of ftp_config.json. Every enabled channel receives the result of each run, including its log.

Telegram

Create a bot with @BotFather. For chat_id use your user ID (@userinfobot) or a channel/group ID prefixed with -100.

"telegram": {
  "enabled": true,
  "bot_token": "123456789:AABBcc...",
  "chat_id": "-100123456789"
}

SMTP

Any SMTP server. Use port: 587 with use_ssl: false for STARTTLS, or port: 465 with use_ssl: true for implicit TLS. For Gmail, use an App Password.

"smtp": {
  "enabled": true,
  "host": "smtp.gmail.com",
  "port": 587,
  "use_ssl": false,
  "username": "you@gmail.com",
  "password": "app-password",
  "from": "cPanelVault <you@gmail.com>",
  "to": "recipient@example.com"
}

Resend

Sign up at resend.com, verify your sender domain and create an API key.

"resend": {
  "enabled": true,
  "api_key": "re_xxxx...",
  "from": "cPanelVault <backup@yourdomain.com>",
  "to": "recipient@example.com"
}

Portainer

Create the config on the Docker host first (e.g. /opt/cpanelvault/ftp_config.json), then add a stack (Stacks → Add stack → Web editor):

services:
  cpanelvault:
    image: gfsolone/cpanelvault:latest
    ports:
      - "8080:8080"
    volumes:
      - /opt/cpanelvault/ftp_config.json:/app/ftp_config.json:ro
      - cpanelvault_backups:/backups
      - cpanelvault_data:/data
    environment:
      TZ: Europe/Rome
    restart: unless-stopped

volumes:
  cpanelvault_backups:
  cpanelvault_data:

To upgrade: Stacks → cpanelvault → Update the stack with Re-pull image enabled.

CLI

The same image (or a local pip install -r requirements.txt) provides a command-line interface. Inside the container, prefix commands with docker compose exec cpanelvault so they share the lock and status with the web UI.

# Back up one host, or all of them sequentially
python main.py backup cpanel1
python main.py backup --all

# Remove expired archives (preview first)
python main.py clean cpanel1 --dry-run
python main.py clean --all

# Web UI + scheduler (what the container runs)
python main.py serve --port 8080

# Use a different config file
python main.py --config /path/to/config.json backup --all

backup exits with code 1 if any host fails or is skipped, so it can be used from cron or scripts.

REST API

curl -X POST http://localhost:8080/backup/cpanel1
curl http://localhost:8080/api/status

Behaviour & FAQ

When are local archives deleted?

An archive expires when it's older than the host's retention_days, counted from its download (file modification time). Expired archives are removed by the cleanup step at the end of the next backup of that host, which runs only after the new archive has been downloaded: a run that fails earlier (backup request, wait or download) deletes nothing. The Backups page shows the run that will remove each archive; python main.py clean <host> removes them immediately.

Can two backups of the same account overlap?

Not when they use the same host name. Only one backup per lock key runs at a time, whether it's started by the scheduler, the Run now button or the CLI. The lock is keyed on the FTP host (case, ftp. prefix and trailing dot ignored) plus cpanel_username, so config entries with the same host and username are serialized too: the entry actually running shows Running…, the others show Busy, and a second run is skipped with a warning.

cPanelVault can't tell that two different host names lead to the same account (e.g. the customer domain and the provider's server hostname): such entries get separate locks and could run at the same time, racing on the same remote archive. Use the same host value for every entry of one account.

What if the container is stopped mid-backup?

At the next start, a backup left in the "running" state is marked as interrupted. Partially downloaded archives are resumed by the next run.

What happens on network problems?

The cPanel backup request is retried after 10 and 30 minutes on connectivity errors; FTP downloads retry every 10 seconds and resume where they stopped; remote deletes are retried up to 5 times. If the backup volume doesn't have enough free space, the download is aborted up front with a clear error.

Where are the logs?

On stdout (docker compose logs -f), in the dashboard's live log for each run, and in notifications. Routine dashboard refreshes and healthchecks are kept out of the access log unless QUIET_ACCESS_LOG=false.