Backups

In OpenPanel, backups are configurable directly by the panel users, unlike other panels where backups are managed by the admin.

This empowers users to define their own backup schedules, choose exactly what to back up, and select from a wide range of supported destinations. As a result, administrators have fewer tasks to manage, and users gain greater control and flexibility.

Destinations​

OpenPanel supports the following destinations:

• S3 storage - AWS S3, Filebase, MinIO, etc.
• WebDAV - Remote backups using WebDAV.
• SSH - Remote backups via SSH to another server.
• Azure - Remote backups to Azure Blob Storage.
• Dropbox - Remote backups to Dropbox cloud storage.

User can select destination from Backups > Destination page.

Once backup is selected, it's options are available on Backups > Configuration tab.

SSH/SFTP​

S3​

WebDAV​

Azure​

Dropbox​

Set up Dropbox storage backend:

1. Create a new Dropbox App in the App Console
2. Open your new Dropbox App and copy the DROPBOX_APP_KEY and DROPBOX_APP_SECRET
3. Click on Permissions in your app and make sure, that the following permissions are cranted (or more):
   • files.metadata.write
   • files.metadata.read
   • files.content.write
   • files.content.read
4. Replace APPKEY in https://www.dropbox.com/oauth2/authorize?client_id=APPKEY&token_access_type=offline&response_type=code with the app key from step 2
5. Visit the URL and confirm the access of your app. This gives you an auth code -> save it somewhere!
6. Replace AUTHCODE, APPKEY, APPSECRET accordingly and perform the request from your terminal:

   curl https://api.dropbox.com/oauth2/token \
   -d code=AUTHCODE \
   -d grant_type=authorization_code \
   -d client_id=APPKEY \
   -d client_secret=APPSECRET
   
7. Execute the request. You will get a JSON formatted reply. Use the value of the refresh_token for the last setting DROPBOX_REFRESH_TOKEN
8. You should now have DROPBOX_APP_KEY, DROPBOX_APP_SECRET and DROPBOX_REFRESH_TOKEN set. These don’t expire.

Encryption​

Backup encryption is by default disabled and needs to be enabled by the Administrator first.

All of the encryption options are mutually exclusive. Provide a single option for the encryption scheme of your choice.

Rotation​

Source​

By default, everything will be backed up. In case you need to backup only a specific data, set BACKUP_SOURCES. On the Backups > Configuration page this is presented as a dropdown with the following options:

Databases are not copied from their live data directories. Right before the archive is created, every MySQL/MariaDB database is dumped with mysqldump/mariadb-dump (--single-transaction --routines --triggers --events) and every PostgreSQL database with pg_dump, into backup/mysql/<database>.sql and backup/postgres/<database>.sql. If any database fails to dump, the whole backup run fails so it doesn't go unnoticed. The names of the dumped databases are also written to a small backup/00-meta/ folder that is always the first thing in the archive, so the panel can index a backup without downloading it.

Emails and DNS zones are backed up too. Each domain's mailboxes are mounted into the backup at backup/emails/<domain>/ (the older backup/mail/ folder only holds links to them) and each domain's DNS zone at backup/dns/<domain>.zone. The backup/00-meta/ folder also lists the website files, mailboxes, domains and DNS zones in the backup, so single items can be restored without downloading the whole archive.

Schedule​

Backups can be run on fixed scheduled that are defined as a cron expression. BACKUP_CRON_EXPRESSION is used to schedule the backup job, a cron expression represents a set of times, using 5 or 6 space-separated fields.

Month and Day-of-week field values are case insensitive. "SUN", "Sun", and "sun" are equally accepted. Refer to sites like crontab.guru for help.

If no value is set, @daily will be used, which runs every day at midnight.

Compression​

Names​

Options here are available byt disabled by default and need to be manually enabled by the Administrator first.

Exclude​

BACKUP_EXCLUDE_REGEXP - When a value is given, all files in BACKUP_SOURCES whose full path matches the regular expression will be excluded from the archive. Regular Expressions can be used as from the Go standard library. Example: \.log$.

The default is \.(log|tar\.gz)$, which skips log files and .tar.gz archives, such as the full account backups that opencli user-backup stores in _backups/.

Notifications​

Notifications (email, Slack, etc.) can be sent out when a backup run finishes.

NOTIFICATION_URLS​

Configuration is provided as a comma-separated list of URLs as consumed by shoutrrr

Email​

URL Format:

smtp://username:password@host:port/?from=fromAddress&to=recipient1[,recipient2,...]

URL Fields:

• Username – SMTP server username
  Default: empty
  URL part: smtp://username:password@host:port/

• Password – SMTP server password or hash (for OAuth2)
  Default: empty
  URL part: smtp://username:password@host:port/

• Host – SMTP server hostname or IP address (Required)
  URL part: smtp://username:password@host:port/

• Port – SMTP server port
  Common values: 25, 465, 587, 2525
  Default: 25
  URL part: smtp://username:password@host:port/

Query/Param Props:

Props can be supplied via the params argument or directly in the URL using ?key=value&key=value.

• FromAddress – Email address the mail is sent from (Required)
  Aliases: from

• ToAddresses – Comma-separated list of recipient emails (Required)
  Aliases: to

• Auth – SMTP authentication method
  Default: Unknown
  Possible values: None, Plain, CRAMMD5, Unknown, OAuth2

• ClientHost – Hostname sent to the SMTP server during the HELO phase
  Default: localhost
  Set to "auto" to use OS hostname

• Encryption – Encryption method
  Default: Auto
  Possible values: None, ExplicitTLS, ImplicitTLS, Auto

• FromName – Name of the sender
  Default: empty

• Subject – Subject line of the email
  Default: Shoutrrr Notification
  Aliases: title

• UseHTML – Whether the message is in HTML format
  Default: ❌ No

• UseStartTLS – Whether to use StartTLS encryption
  Default: ✔ Yes
  Aliases: starttls

Bark​

URL Fields:

• DeviceKey – The key for each device (Required)
  URL part: bark://:devicekey@host/path

• Host – Server hostname and port (Required)
  URL part: bark://:devicekey@host/path

• Path – Server path
  Default: /
  URL part: bark://:devicekey@host/path

Query/Param Props:

Props can be either supplied using the params argument, or through the URL using ?key=value&key=value etc.

• Badge – The number displayed next to App icon
  Default: 0

• Category – Reserved field, no use yet
  Default: empty

• Copy – The value to be copied
  Default: empty

• Group – The group of the notification
  Default: empty

• Icon – A URL to the icon, available only on iOS 15 or later
  Default: empty

• Scheme – Server protocol, http or https
  Default: https

• Sound – Value from Bark Sounds
  Default: empty

• Title – Notification title, optionally set by the sender
  Default: empty

• URL – URL that will open when notification is clicked
  Default: empty

Discord​

URL Format:

discord://token@webhookid

URL Fields:

• Token – (Required)
  URL part: discord://token@webhookid/

• WebhookID – (Required)
  URL part: discord://token@webhookid/

Query/Param Props:

Props can be either supplied using the params argument, or through the URL using ?key=value&key=value etc.

• Avatar – Override the webhook default avatar with specified URL
  Default: empty
  Aliases: avatarurl

• Color – The color of the left border for plain messages
  Default: 0x50D9ff

• ColorDebug – The color of the left border for debug messages
  Default: 0x7b00ab

• ColorError – The color of the left border for error messages
  Default: 0xd60510

• ColorInfo – The color of the left border for info messages
  Default: 0x2488ff

• ColorWarn – The color of the left border for warning messages
  Default: 0xffc441

• JSON – Whether to send the whole message as the JSON payload instead of using it as the content field
  Default: ❌ No

• SplitLines – Whether to send each line as a separate embedded item
  Default: ✔ Yes

• Title
  Default: empty

• Username – Override the webhook default username
  Default: empty

Creating a Webhook in Discord:

1. Open your channel settings by clicking the gear icon next to the channel name.
2. In the left menu, click Integrations.
   
3. On the right, click Create Webhook.
   
4. Set the name, channel, and icon to your preference, then click Copy Webhook URL.
   
5. Press Save Changes. 6 Format the service URL:

   https://discord.com/api/webhooks/693853386302554172/W3dE2OZz4C13_4z_uHfDOoC7BqTW288s-z1ykqI0iJnY_HjRqMGO8Sc7YDqvf_KVKjhJ
                                    └────────────────┘ └──────────────────────────────────────────────────────────────────┘
                                        webhook id                                    token
   
   discord://W3dE2OZz4C13_4z_uHfDOoC7BqTW288s-z1ykqI0iJnY_HjRqMGO8Sc7YDqvf_KVKjhJ@693853386302554172
             └──────────────────────────────────────────────────────────────────┘ └────────────────┘
                                             token                                    webhook id
   

NOTIFICATION_LEVEL​

By default, notifications would only be sent out when a backup run fails. To receive notifications for every run, set NOTIFICATION_LEVEL to info instead of the default error.

Triggering a Backup​

You can manually trigger a backup at any time, regardless of the scheduled settings. To do this, ensure the Docker feature is enabled. Then:

1. Navigate to Containers > Terminal.
2. Select the Backup container.
3. In the terminal, type the following command and press Enter:

backup

Restore & Download​

The Restore & Download page (/backups/list) lets you browse the backup files that already exist on your configured destination, restore them back onto your account, or download them to your computer. It works with every destination: SSH/SFTP, S3, WebDAV, Azure Blob Storage and Dropbox.

Click Reindex Destination to connect to the remote destination and list the available backup archives. Reindexing runs in the background and the page updates automatically once it finishes. Only the backup/00-meta/ folder at the start of each archive is read, and archives that were already indexed are not read again. Older archives without that folder are still listed in full (on SSH/SFTP with tar -tzf on the remote server, on other destinations by reading the whole archive).

The page opens with an overview: the number of backups, the latest backup, their total size and the last restore, followed by a tile for each type of data you can restore. Click a tile to see its backups, newest first, each with the date it was taken (shown in your browser's time zone) and its size. The tabs at the top switch between types, Overview goes back to the tiles, and the Search box above each list filters it.

Everything, Website Files and Cron Jobs​

These tabs list whole backups. Select one and the bar at the bottom shows Download and Restore.

• Everything – every backup, with a Contents column showing what is in it (website files, databases, emails, domains and cron jobs, with how many of each). Restores everything in it: website files, databases, emails, domains with their DNS zones and cron jobs.
• Website Files and Cron Jobs – the backups that contain that part. Restores only that part of the selected backup; restoring cron jobs also restarts the cron container.

Choosing single files​

On Website Files, select a backup and click Choose files to browse it folder by folder. Tick single files or whole folders and click Restore selected, or click the download icon next to a file to download just that file. Only the part of the archive up to the last picked item is read from the destination.

Databases, Emails and Domains​

These tabs list every database, email account and domain found in your backups, once each, with the size (and message count for email accounts) and how many backups contain it. The newest backup is used unless you pick another one from the dropdown, and you can select several to restore them together.

• Restoring a domain brings back its webserver configuration (+ VirtualHost), the PHP version it uses (+ PHP version, that PHP is started and set for the domain) and, when the backup has it, its DNS zone (+ DNS zone), then restarts your webserver and reloads the zone with a new serial number.
• A domain you deleted from your account is marked Will be added and is added back first.
• Suspended domains are marked Suspended and can't be restored until they are unsuspended.
• Email accounts can only be restored for domains on your account. An email account whose domain is gone is marked Restore the domain first.

Restoring​

Select a backup (or databases, email accounts, domains or files) and click Restore. The Restore Summary lists the items that will be restored; click Restore Selected Items to add them to the queue. Restores run in the background, one at a time per account, so you can close the page while they run. Each database is dropped, recreated and its dump is piped into the mysql/mariadb or psql client inside your database container.

Queue and logs​

Under Restore activity on the overview (or the tabs at the top), Queue shows what is waiting or being restored and Logs shows your latest 100 restores: what was restored, from which backup, when it finished, how long it took and whether it worked, with the result or the error. The summary at the top shows when the last restore finished, or how many are in the queue. A restore that was running when the panel restarted is logged as failed, the ones still waiting in the queue continue.

Downloading​

Select a backup and click Download to stream the archive from the destination straight to your browser. On Databases, Emails and Domains, Download gives you only what you selected: a single database as its .sql dump, anything else as a .tar.gz with just those items (one per backup you picked from).

Troubleshooting​

Error *error copying archive: ssh.(sshStorage).Copy: error creating file: file does not exist indicates that the configured directory does not exist on destination:

time=2025-07-22T11:21:05.117Z level=ERROR msg="Fatal error running command: file does not exist" error="main.(*command).runAsCommand: error running script: main.runScript.func4: error running script: main.(*script).copyArchive: error copying archive: ssh.(*sshStorage).Copy: error creating file: file does not exist"

Credits & License​

The backup functionality in OpenPanel uses offen/docker-volume-backup by offen.software. Thank you to its authors and contributors.

• Setting descriptions in the Destinations, Encryption, Rotation, Source, Schedule, Compression, Names, Exclude and Notifications sections are adapted from the docker-volume-backup configuration reference and how-to guides, Copyright © offen.software and contributors. That content is licensed under the Mozilla Public License 2.0, and the source is available at github.com/offen/docker-volume-backup.
• Notification service URL formats and options are adapted from the shoutrrr documentation, Copyright © containrrr contributors, licensed under the MIT License.