# Backups and restore

> Every Artavolo instance can produce one encrypted archive that holds everything needed to rebuild it: the application database, the data database (one table per sheet) and the uploaded files. The Enterprise edition ru...

Source: https://artavolo.com/docs/backups

Every Artavolo instance can produce one encrypted archive that holds everything needed to rebuild it: the application database, the data database (one table per sheet) and the uploaded files. The Enterprise edition runs this on a schedule and can copy the archive to an S3-compatible bucket.

## The encryption key

Set `BACKUP_ENCRYPTION_KEY` before the first backup:

- Docker: `ARTAVOLO_BACKUP_ENCRYPTION_KEY` in `.env` (`openssl rand -hex 32`), then `docker compose up -d`.
- LAMP: `define('BACKUP_ENCRYPTION_KEY', '...');` in `includes/config.php`.

Store a copy of the key outside the server (password manager, printed in a safe). An archive cannot be opened without it, and there is no recovery path. Rotating the key only affects new archives; keep old keys as long as you keep old archives.

Archives are `artavolo-backup-YYYYMMDD-HHMMSS.abk`: AES-256-CTR with a random IV, authenticated with HMAC-SHA256 over the whole file. The integrity tag is checked before anything is decrypted, so a wrong key or a damaged file is refused up front.

## Running a backup

From the shell (any edition):

```bash
# Docker
docker compose exec -u www-data app php utilities/backup.php
# LAMP
php utilities/backup.php
```

Options: `--no-uploads` (databases only), `--path=/mnt/backups`, `--keep=30` (retention in days), `--no-s3`, `--plain` (unencrypted zip, only for moving data by hand). The archive lands in `data/backups/` (Docker: the `app_backups` volume) unless a path is configured.

From the administration (Enterprise): Settings → Backups → "Run a backup now". The same page configures the daily schedule (hour, server time), the local folder, retention, whether uploads are included, and the S3-compatible target. The cron job that ships with the instance starts the run within five minutes of the chosen hour. A failed run e-mails all administrators; every run appears in the audit log as `backup.run` or `backup.failed`.

Copy archives off the host. With Docker: `docker compose cp app:/var/www/html/data/backups ./backups`. With an S3 target the copy happens automatically after each run; retention applies there too.

## Checking an archive

```bash
php utilities/restore.php artavolo-backup-20260911-030001.abk --dry-run
```

This verifies the tag, decrypts to a temporary folder, prints the manifest (version, instance, creation time) and the size of each part, and removes the temporary files. Do this monthly, and once on a scratch machine to prove the full restore below works.

## Restoring

Restoring replaces the two databases named in `includes/config.php` and copies the uploads over the current ones. Stop the web server (or scale the app container down) first.

```bash
# Docker: a fresh stack with the same .env (same ARTAVOLO_BACKUP_ENCRYPTION_KEY)
docker compose up -d db
docker compose run --rm -u www-data app php utilities/restore.php /var/www/html/data/backups/artavolo-backup-20260911-030001.abk --yes
docker compose up -d

# LAMP
php utilities/restore.php /path/to/artavolo-backup-20260911-030001.abk --yes
php utilities/clear-cache.php
```

`--no-uploads` restores only the databases, `--no-database` only the uploads, `--extract=/tmp/out` unpacks without touching the instance, `--key=...` supplies the key when `config.php` does not exist yet. The restore records `backup.restored` in the audit log.

Restoring into an instance that runs a newer application version is supported: run `php utilities/migrate.php` afterwards so the schema catches up.

## What is not in the archive

`includes/config.php` (contains database credentials and secrets; keep it with the key), the language packs under `lang/` if you edited them, and the licence key (also in the database, so it is restored with it).
