Add Example documentation to Restore volumes from a backup

[bocklucas]

Description

After spending an hour trying to apply the stesp in Restore volumes from a backup, I was finally able to successfully restore from a backup and thought others might benefit from my experience.

Would be cool to see this documentation added to the section or incorporated in some way shape or form.

Proposed Example documentation:

Backup & Restore Example

In this example, we will backup a gitea service via the CLI and then perform a restoration.

Our docker-compose.yaml file written below will be located at gitea/docker-compose.yaml

Setup

docker-compose.yaml

services:
  server:
    image: docker.io/gitea/gitea:1.23.1-rootless
    restart: always
    volumes:
      - data:/var/lib/gitea
      - config:/etc/gitea
    cap_add:
      - SYS_ADMIN
      - DAC_READ_SEARCH
    ports:
      - "3000:3000"
      - "2222:2222"

volumes:
  data:
  config:

1. Save the docker-compose.yaml file below to a similar path above and run docker-compose up -d
2. Navigate to http://localhost:3000 and run through a basic setup of gitea to ensure you have data to benchmark that backup and restoration is working correctly. If done correctly, you should be able to delete the original volumes and restore from your backups with all of your data intact.

Backup Steps

1. Determine the volumes to be backed up, in this case gitea_config and gitea_data
2. Determine the directory you want the backups placed in as we will need to access them later, lets say the user home directory /home/user/Downloads
3. Run the manual backup process for each volume

# Backup the Config volume
docker run --rm \
  -e BACKUP_FILENAME="backup-config-%Y-%m-%dT%H-%M-%S.{{ .Extension }}" \
  -v gitea_config:/backup/config/gitea \
  -v /home/user/Downloads:/archive \
  --entrypoint backup \
  offen/docker-volume-backup:v2.43.3

# Backup the Data volume
docker run --rm \
  -e BACKUP_FILENAME="backup-data-%Y-%m-%dT%H-%M-%S.{{ .Extension }}" \
  -v gitea_data:/backup/data/gitea \
  -v /home/user/Downloads:/archive \
  --entrypoint backup \
  offen/docker-volume-backup:v2.43.3

4. You should now have 2 backup files, 1 titled backup-data-[current timestamp].tar.gz and another one titled backup-config-[current timestamp].tar.gz
5. If you can, go to another machine and download the backups to that machine. If you're operating on the same machine, you'll have to run docker-compose down and then delete the volumes with docker volume rm gitea_config && docker volume rm gitea_data

Restore Steps

1. Now starting from a clean slate, you'll first need to create the volumes for your services before you restore the data to them. Create your volumes using your docker-compose.yaml file, run docker-compose up -d in the gitea directory
2. Once the volumes are created, you need to stop your services in order to restore the volumes, this can be done by running docker-compose down
3. Unzip your backup data in a temporary place

tar -C /tmp -xvf backup-data-[current timestamp].tar.gz
tar -C /tmp -xvf backup-config-[current timestamp].tar.gz

4. Restore the data in the volumes using temporary containers. To do this, we're going to mount the data volume to a temp container, copy the unzipped files from Step 3 over, and then stop and remove the container

# Mount the data volume to a temp container, copy the unzipped files from Step 3 over, and then stop and remove the container

docker run -d --name temp_restore_container -v gitea_data:/backup_restore/data/gitea alpine && docker cp /tmp/backup/data/gitea temp_restore_container:/backup_restore/data && docker stop temp_restore_container && docker rm temp_restore_container

# Mount the config volume to a temp container, copy the unzipped files from Step 3 over, and then stop and remove the container

docker run -d --name temp_restore_container -v gitea_config:/backup_restore/config/gitea alpine && docker cp /tmp/backup/config/gitea temp_restore_container:/backup_restore/config && docker stop temp_restore_container && docker rm temp_restore_container

5. Run docker-compose up -d and your volume restoration should be complete

If you go back to http://localhost:3000 you should be able to login and see your data from before

[m90]

Thanks for this writeup. I'm happy with extending the documentation accordingly, but I am currently a bit unsure about where to put this, as it's much more specific than everything else in the docs right now. I would also be a bit worried about including instructions on how to setup Gitea or any other 3rd party software as otherwise this repo starts being responsible for keeping these instructions up to date.

[bocklucas]

Thanks for this writeup. I'm happy with extending the documentation accordingly, but I am currently a bit unsure about where to put this, as it's much more specific than everything else in the docs right now. I would also be a bit worried about including instructions on how to setup Gitea or any other 3rd party software as otherwise this repo starts being responsible for keeping these instructions up to date.

Ahh, yeah, totally fair! Feel free to modify the write up as well to address the concerns 😁

[ajyey]

@bocklucas I'd also like to add that if you're using docker compose and restoring from a backup onto a new machine, I'm pretty sure if you create those volumes outside of compose ahead of your restore operation docker compose will complain and ask you to mark them as external when you go to bring up your stack. Not really an issue technically, but I (somewhat irrationally) find marking every single volume as external annoying.

Assuming you're starting fresh, the workaround I've found to work quite well is to run docker compose up --no-start with your volumes already declared in your compose file which will create your (empty) volumes and containers. Then restore your volumes into those new empty ones and docker compose up -d as normal

Hope this helps!