Backing up and restoring data is an extremely important part of running servers. It's a virtual safety net against most bad things that can happen. Made a bad config change? Restore a backup. Messed up an update? Restore a backup. Corrupted Drives? Restore a backup.

Not only that, backups can also come in handy when migrating data to other systems, like migrating a development server into a production environment or vice versa.

To make this process as easy as possible, we've written this guide to explain everything you need to know about backing up and restoring your Appwrite instance.

Appwrite consists of multiple sections, and most of it is stateless. This means there are only two main things you need to back up: Appwrite's database (MariaDB) and the Docker volumes that store functions, data, and uploads. The rest can be automatically handled and regenerated by Appwrite.

Please note that all these commands need to be run within the same directory as Appwrite's docker-compose.yml

With all that said, lets begin!

Backing up the MariaDB Database

Due to the fact that Appwrite uses a Docker image of MariaDB it is extremely easy to dump the entire database with just one command and likewise to restore the dump.

Creating a Database backup is just one command:

docker-compose exec mariadb sh -c 'exec mysqldump --all-databases --add-drop-database -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"' > ./dump.sql

This command does a couple things:

1. Docker-compose launches a temporary shell onto the MariaDB container to start work

2. It runs mysqldump on the server with two specific options -all-databases and -add-drop-database these are important since they ensure that when the backup is restored old data doesn't get overlapped with new data.

3. The output of mysqldump is piped into a dump.sql file. This is your backup.

Restoring the MariaDB database

Restoring the database is similarly easy and also requires just one command to do:

docker-compose exec -T mariadb sh -c 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"' < dump.sql

This command is very simple once you break it down:

1. Docker-compose launches a temporary shell onto the MariaDB container to start work

2. Using the mysql command we restore the dump through a pipe

Backing up your Docker volumes

Appwrite stores various types of data in Docker volumes, including file uploads and Cloud Function data. These volumes help coordinate data between the central Appwrite container and the various Appwrite workers. It's crucial to back up these uploads since they contain all your app's file uploads. Keep in mind that these backup commands might take some time to run, depending on the amount of data you need to back up.

Before running these commands is it highly recommended to shut down your Appwrite instance to ensure you get a complete backup.

To backup the functions volume the command is:

mkdir -p backup && docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/backup ubuntu bash -c "cd /storage/functions && tar cvf /backup/functions.tar ."

and to backup the uploads volume the command is:

mkdir -p backup && docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/backup ubuntu bash -c "cd /storage/uploads && tar cvf /backup/uploads.tar ."

Finally, also backup your builds volume:

mkdir -p backup && docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/backup ubuntu bash -c "cd /storage/builds && tar cvf /backup/builds.tar ."

Both these commands do similar things and when you break them down they are pretty simple.

1. Start a new Docker container. This Docker container has a few special options

• -rm will delete the container once it's done running. The reason we want this is because this container is only being used to package up our backup and give it to the host machine.

• -volume-from This flag special as it will mount all of the volumes of the container we give it. To get the container ID we want we use a $(docker-compose ps -q appwrite) to get the ID within the command

• v This flag is being used to mount a volume onto our new container which will give us access to a backup folder we created using the mkdir command at the start

ubuntu is the image we are basing our new container on

1. Finally with this command created we change directories into the normal Appwrite mount point for uploads and create a tarball which will be created in the backup directory where we will be able to access it.

Once these commands are run you should find a new backup folder which containsuploads.tar and functions.tar these are your backups. Keep them safe.

Restoring your Docker volumes

Restoring your Appwrite volumes is fairly simple as well. Move the backup folder you just created to your destination machine next to the docker-compose.yml file and simply run the following commands to restore the backup.

Please note that the Appwrite instance should be shut down while running these commands.

Restoring functions volume:

docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/restore ubuntu bash -c "cd /storage/functions && tar xvf /restore/functions.tar --strip 1"

Restoring uploads volume:

docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/restore ubuntu bash -c "cd /storage/uploads && tar xvf /restore/uploads.tar --strip 1"

Restoring the builds volume:

docker run --rm --volumes-from "$(docker-compose ps -q appwrite)" -v $PWD/backup:/restore ubuntu bash -c "cd /storage/builds && tar xvf /restore/builds.tar --strip 1"

This command creates a new temporary Docker container similar to the backup command, but instead of creating a backup, it extracts the tar file back into the functions and uploads endpoints to restore the backup.

Copy your _APP_OPENSSL_KEY_V1 environment variable

Appwrite keeps all your data encrypted, to ensure that all your files, hashes and all other encrypted data is accessible to your new Appwrite instance make sure to copy the _APP_OPENSSL_KEY_V1 from your original instance to your new instance.

Conclusion

To create a complete Appwrite backup, you'll need to back up MariaDB and the two specified volumes. Once you’ve done this, ensure the backup is stored safely. The best practice is to store it in multiple locations, both locally and across different cloud services. Like with any cloud-native application, regular backups of your Appwrite instance are essential to prevent data loss in case of a server failure.

This process makes migrating an Appwrite installation simple. Just copy the backup files to another server and run the restore steps.

We hope you enjoyed this article! We love contributions and encourage you to take a look at our open issues and ongoing RFCs.

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans.

Here are some handy links for more information:

• Appwrite contribution guide

• Appwrite Github

• Appwrite docs