+page.markdoc

---
layout: post
title: "How to back up and restore your Appwrite data"
description: Learn how to back up and restore your Appwrite files.
date: 2024-08-07
cover: /images/blog/appwrite-backups-and-restores/cover.png
timeToRead: 3
author: bradley-schofield
category: product
---

Updated on October 6, 2025

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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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 contains`uploads.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:

```bash
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:

```bash
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:

```bash
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](https://github.com/appwrite/appwrite/issues) and [ongoing RFCs](https://github.com/appwrite/rfc/pulls).

If you get stuck anywhere, feel free to reach out to us on our [friendly support channels](https://appwrite.io/discord) run by humans.

# Frequently asked questions (FAQs)

**1. Why should I back up my Appwrite instance regularly?**

Backups protect your data from accidental deletions, failed updates, or hardware issues. They also make it easy to migrate between servers or environments. Regular backups ensure you can restore your setup quickly without losing user data or configurations.

**2. What parts of Appwrite do I need to back up?**

You only need to back up two main things:

- The MariaDB database (stores all project data)
- The Docker volumes for functions, uploads, and builds.

Everything else is stateless and can be regenerated automatically by Appwrite.

**3. Can I back up Appwrite while it’s running?**

It’s possible, but not recommended. To avoid incomplete or inconsistent backups, it’s best to shut down your Appwrite instance before running backup commands. This ensures all data is captured correctly.

**4. How do I restore an Appwrite backup to a new server?**

Move your backup files to the new server, place them next to the `docker-compose.yml`, and run the restore commands for the database and volumes. Don’t forget to copy your `_APP_OPENSSL_KEY_V1` environment variable, it’s required to decrypt your data.

**5. Where should I store my Appwrite backups?**

Keep backups in multiple safe locations, ideally a mix of local storage and cloud storage. This protects you from local disk failures and makes recovery easier if your primary environment goes down.

**6. How often should I back up my Appwrite database?**

It depends on how frequently your data changes. For active projects, schedule daily or hourly backups of the MariaDB database to prevent data loss. You can automate this using cron jobs or CI pipelines. For smaller or less active projects, weekly backups are usually enough. Just make sure to store them securely and test restores occasionally.

Here are some handy links for more information:

- [Appwrite contribution guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md)
- [Appwrite Github](https://github.com/appwrite)
- [Appwrite docs](https://appwrite.io/docs)