Cloudbox Backup and Restore

• Intro
• Cloudbox Backup
• Cloudbox Restore

---

Intro

Backup and Restore is a built-in feature of Cloudbox that makes it easy to back-up your entire Cloudbox setup, with the ability to restore it anywhere.

Note 1: Only app data located in '/opt' and relevant config files are backed up. For more details, see here.

Note 2: If you wish to move your Cloudbox to another server via Backup / Restore, see Migrating Cloudbox.

Note 3: You will need local free disk space equal to the size of your /opt dir to store the tarballs, even if you are ultimately storing the backup on a remote system [Google/rsync/etc]. The backup system does not preflight this, so if you have insufficient space the backup script will fill your disk and then fail which will then have knock-on effects as the apps can no longer write to their databases and so forth. This is something you really want to avoid.

Cloudbox Backup

Cloudbox Backup backs up the Docker container app data (i.e. /opt), and all relevant config files, and uploads it to an Rclone or Rsync remote (if they are enabled).

Backup can be ran manually (steps below), for an immediate, one-time backup, or scheduled to run periodically.

Note: During backup, all Cloudbox managed Docker containers will be shut down (i.e. Plex will be unavailable) while the tarball files are being made. If /opt is on a BTRFS volume, this downtime is minimal as a snapshot is taken and the containers restarted within a minute or so, then the remainder of the backup can operate off that snapshot.

Steps to run a manual backup:

Master branch

1. Go into your Cloudbox folder

   cd ~/cloudbox

2. Make sure backup settings (i.e. backup_config.yml) are filled out.

3. Run the backup command

   sudo ansible-playbook cloudbox.yml --tags backup

   via screen:

   screen -dmS cloudbox-backup sudo ansible-playbook cloudbox.yml --tags backup

   screen -r

   CTRL A + D

Develop branch

1. Make sure backup settings (i.e. ~/cloudbox/backup_config.yml) are filled out.

2. Run the backup command

   cb install backup

   via screen:

   screen -dmS cloudbox-backup cb install backup

   screen -r

   CTRL A + D

For scheduled backups, see here.

If for some reason your backup stops/ you accidentally reboot the server etc.: You'll need to remove the backup.lock file in your cloudbox directory, otherwise tags will not run.

Cloudbox Restore

Cloudbox Restore downloads the backup from the cloud (if Rclone or Rsync were enabled) and restores it to the /opt folder (this is done automatically and requires no manual intervention).

If a local backup (e.g. /opt tarball files) already exists in the backup folder, those tarball files will be used instead.

Backup can be restored on the same server or brand new one, with everything exactly as you left it at the time of backup. See Migrating Cloudbox for more info.

Steps below assume you are restoring to a new / wiped server.

There are eight steps below. Steps 1, 5, 6, 7, 8 are REQUIRED. Whether you need 2, 3, and/or 4 depends on how YOU configured Cloudbox.

1. REQUIRED Install dependencies and download the Cloudbox project repository.

2. OPTIONAL If the Restore Service was enabled in settings (i.e. restore_service credentials were supplied in backup_config.yml), you will be able automatically restore the config files into the ~/cloudbox folder.

   To do so run the following command (replace USERNAME and PASSWORD with your restore_service credentials).

   curl -s https://cloudbox.works/scripts/restore.sh | bash -s 'USERNAME' 'PASSWORD'
   

   NOTE: Wrap your USERNAME and PASSWORD in quotes just as shown there.

   IF YOU ARE RUNNING DEVELOP BRANCH:

   curl -s https://cloudbox.works/scripts/restore_develop.sh | bash -s 'USERNAME' 'PASSWORD'
   

   NOTE: These are not [necessarily] your login credentials. This is a username/password that you have to enter yourself in the backup_config.yml file. The Cloudbox install does not automatically fill these in. If you did not fill these in yourself, then the Cloudbox Restore Service is NOT enabled.

3. OPTIONAL

   If the Cloudbox Restore Service was not enabled (i.e. restore_service credentials were NOT supplied in backup_config.yml)... (CLICK TO EXPAND)

   
   
   • Find the following files in your backup and drop them into the ~/cloudbox folder:
   
   
   • ansible.cfg
   
   
   • accounts.yml
   
   
   • settings.yml
   
   
   • adv_settings.yml
   
   
   • backup_config.yml
   
   
   • rclone.conf
   
   
   • Note 1: These files were backed up separately from the backup tarball files so they can easily be copied here.
   
   
   • Note 2: During the restore process, the rclone.conf file will be moved to ~/.config/rclone/rclone.conf.
   
   
   • Note 3: The /opt folder gets downloaded/restored automatically in the next step, and doesn’t require manual downloading or unpacking.
   
   

4. OPTIONAL If you had Ansible Vault set up before, you'll need to create an Ansible Vault password file using the same vault password as last time.

   echo YOUR_VAULT_PASSWORD > /root/.ansible_vault

   of course, that should be your vault password, not literally YOUR_VAULT_PASSWORD.

5. REQUIRED Run preinstall command to create a user account:

   cd ~/cloudbox
   sudo ansible-playbook cloudbox.yml --tags preinstall

   IF YOU ARE RUNNING DEVELOP BRANCH:

   cb install preinstall

   Note: It's ok to do this in root as it will create a new user account and move the cloudbox folder and config files to that new user's home folder.

   Now log out of your root session and log in as the user account from your accounts.yml file.

6. REQUIRED Run the restore command:

   Note: Do not run this command while logged in as root. Log in as your user account; the account you specified in accounts.yml

   cd ~/cloudbox
   sudo ansible-playbook cloudbox.yml --tags restore

   Note: If you are getting an error, verify that you are not logged in as root. You should be logged in as the user account specified in accounts.yml..

   Note: If you are getting an error for rclone such as permission denied reboot the system then sign in as your user then run the restore tag again.

   That error will include: ... Failed to open log file: open /root/cloudbox/restore_rclone.log: permission denied", ...

   If you get an error related to a misconfigured rclone.conf file, check that file and make sure things look normal. Also run rclone config to check that a remote has actually been configured.

   THIS COMMAND DOES NOT RESTORE ANY APPS. It only copies your backup data files onto this machine. You need to take the following step to reinstall docker, the other support software, and recreate all the containers that actually use that backup data.

7. REQUIRED Install the relevant Cloudbox type: Cloudbox, Mediabox, or Feederbox. Example below. THIS STEP IS NOT OPTIONAL. This is the same tag you ran the first time you set this system up, so if this was an all-in-one, run the cloudbox tag, etc. This step will install all the common things that any other tag will require, and if at this point you try to install a single app tag it will fail with a non-obvious error.

   Note: Do not run this command while logged in as root. Log in as your user account; the account you specified in accounts.yml

   Example:

   sudo ansible-playbook cloudbox.yml --tags cloudbox

   IF YOU ARE RUNNING DEVELOP BRANCH:

   cb install cloudbox

8. REQUIRED Reboot.

9. If you had any extra, or non-default, containers previously (e.g Community Roles), you can install those now.

All applications, and their data, will now be restored, except for as listed below.

Things not restored [or not set up completely] by Cloudbox Restore

1. custom service files

   These are backed up and restored to /opt/systemd-backup, but they are not copied into place and enabled. You will have to do that manually.

   Notably this will include things like:

   • extra rclone_vfs mount services
   • custom mergerfs setups

   For example, if your custom mergerfs.service contains something like this:

     /mnt/local=RW:/mnt/remote=NC:/mnt/td-movies=NC:/mnt/td-tv=NC:/mnt/td-music=NC:/mnt/td-audiobooks:NC /mnt/unionfs
   

   You will need to:

   • recreate those dirs
   • copy in, activate, and start the services that are creating those mount points
   • copy in, activate, and start your custom mergerfs service.