Backups

The shop can back itself up automatically — daily, weekly or monthly — to your own private GitHub repository. If the server ever crashes or gets lost, you install the shop on a new server and load the latest backup. Nothing is lost except what happened after that backup.

Setting it up takes about 5 minutes and is done once.

---

What is in a backup?

Each backup is a single ZIP file:

File	Content
database.sql	The complete database: orders, invoices, customers, products, stock, coupons, pages, all settings, admin accounts
uploads/	All uploaded files: product images, logos, banners, digital downloads (can be switched off)
RESTORE.txt	Short restore instructions
backup-info.json	Date and shop name

The ZIP file is encrypted with age before it leaves the server and uploaded as shop-backup-….zip.age. On GitHub, every backup is shown as a release (e.g. Backup 2026-10-25 02:00 UTC) with that file attached. Old backups are deleted automatically. You choose how many to keep.

Only you can open the backups. The shop knows only your public key (age1…): it can encrypt, but never decrypt. Your private key stays on your own computer. A leaked GitHub token or a hacked GitHub account exposes nothing readable. Backups are only ever uploaded encrypted: without a public key, no backup is made.

Keep the repository private anyway. The shop refuses to back up into a public repository. Turn on two-factor authentication for your GitHub account.

---

Setup

You need a free GitHub account. If you don't have one yet, sign up at github.com/signup.

Step 1 — Create a private repository

1. Open github.com/new.
2. Repository name: e.g. shop-backups
3. Select Private.
4. Leave everything else as it is and click Create repository.

That's it. The repository may stay empty; the shop sets it up on the first backup.

Step 2 — Create an access token

The token is like a password that only lets the shop write into this one repository and nothing else. Keep it in your password manager: you need it again to restore a backup on a new server.

1. Open github.com/settings/personal-access-tokens/new (GitHub → your picture → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token).
2. Token name: e.g. Shop backup
3. Expiration: pick No expiration if offered, otherwise the longest possible duration (see Renewing the token).
4. Repository access: choose Only select repositories and select your backup repository (shop-backups).
5. Permissions → Repository permissions → Contents → set to Read and write. (Metadata: Read-only is selected automatically. No other permissions are needed.)
6. Click Generate token and copy the token (it starts with github_pat_…). GitHub shows it only once.

Step 3 — Create your encryption key (on your own computer)

The admin shows the same steps under Settings → Export & Backups → Encryption → How do I get a key?

1. Install age (free, open source, nothing to sign up for):

   System	Command
   Windows	PowerShell: winget install FiloSottile.age, then close it and open a new PowerShell window
   macOS	Terminal: brew install age (needs Homebrew)
   Debian / Ubuntu	sudo apt install age
   Fedora	sudo dnf install age

2. Create your key pair:

   age-keygen -o shop-backup-key.txt

   It prints Public key: age1…. That is your public key; you'll paste it into the admin in step 4.

3. shop-backup-key.txt holds your private key (AGE-SECRET-KEY-1…). Without it, no backup can ever be restored. Keep it in two places: your password manager and a second place that is not the shop server (e.g. a USB stick in a drawer). Never upload it to the shop or to GitHub, don't send it by e-mail, and don't keep it in a project folder.

   Lost the public key? age-keygen -y shop-backup-key.txt prints it again.

More than one key? You can enter several public keys, one per line, e.g. a second key kept in a safe for emergencies. Every backup is then encrypted to all of them, and each matching private key opens it.

Step 4 — Connect the shop

1. Log in to the admin as a superadmin.

2. Go to Settings → Export & Backups. The first box is Automatic Backups to GitHub.

3. GitHub repository: your-account/shop-backups — or just paste the link to the repository.

4. Access token: paste the token.

5. Click Test connection. You should see "Connected: … is private and the token can store backups there."

6. Encryption → Your public key: paste the Public key: age1… line from Step 3 (the whole line is fine; the shop picks out the key and shows 1 public key recognized). If you paste the private key by mistake, the field is cleared at once and nothing is sent.

7. Click Test the key. A small file backup-key-test.txt.age is downloaded. Open it on your computer:

   age -d -i shop-backup-key.txt backup-key-test.txt.age

   It prints It works! → your private key opens the backups. no identity matched any of the recipients means the public key in the admin does not belong to this key file.

8. Choose how often:

   • Daily — every night (recommended for shops with daily orders)
   • Weekly — every Sunday
   • Monthly — on the 1st of each month

9. Choose at what time (your local time; a night hour is best) and how many backups to keep (e.g. 30 daily backups = one month of history, 12 monthly backups = one year).

10. Tick Automatic backups switched on and click Save backup settings.

The first backup starts right away. After a minute or two the box shows Last backup with a green tick, and View backups opens the list on GitHub.

You can click Back up now at any time, e.g. before making big changes to the shop.

---

Is it working?

• The backup box in the admin shows the last backup, its size and the next scheduled backup.
• On GitHub, open your repository → Releases (right side) to see all backups.
• If a backup fails, the shop retries every hour and sends one email to all superadmins that have an email address (or to the shop's support address). This needs working email settings (Settings → Email & Auth Policies). You can preview this email there with the test email type Automatic Backup Failed.

Common error messages:

Message	What to do
No age public key is set: backups are only uploaded encrypted	Enter your public key (Step 3 and Step 4, point 6) and save. Until then no backup is made.
This contains your PRIVATE key …	You pasted the private key or the whole key file. It was not saved. Paste only the Public key: age1… line.
GitHub rejected the access token	The token is wrong, expired or deleted. Create a new one (Step 2), paste it and save.
Repository … was not found	Check the repository name. The token must have access to exactly this repository (Step 2, point 4).
The access token may not … in …	The token is missing Contents: Read and write (Step 2, point 5). Edit the token on GitHub and change it.
… is a public repository	Make the repository private: repository → Settings → Danger Zone → Change visibility.
pg_dump is not installed	The backend image is older than this feature. Rebuild: docker compose up -d --build backend
The backup is … GitHub accepts files up to 2 GB	Too many/large uploads. Untick Include uploaded files and back up the media library separately (see below).

---

Renewing the token

If GitHub did not offer No expiration, the token stops working on its expiry date. The admin shows a warning 14 days before, and the last backup message mentions it too. To renew:

1. Create a new token exactly as in Step 2.
2. In the admin, paste it into Access token and click Save backup settings.

The old token can then be deleted on GitHub.

---

Changing the encryption key

Create a new key pair (Step 3), paste the new public key in the admin and save. New backups are encrypted to the new key. Backups already on GitHub can still only be opened with the old private key, so keep the old key file until those backups have been deleted (with 30 daily backups: one month).

To add a second key instead (e.g. an emergency key), put both public keys in the field, one per line.

Coming from a version before 1.8.0

Older versions uploaded the backups unencrypted (.zip). Since 1.8.0, automatic backups stop until a public key is entered; the admin shows a red notice. Set up the key (Step 3 and Step 4, points 6–7), then click Back up now and check that the new backup on GitHub ends in .zip.age.

The old unencrypted backups stay on GitHub until they are rotated out (or delete them there yourself). They can still be restored as before.

---

Restoring

See Restoring a Backup.

---

Manual backups on the server

Manual backups on the server (in /opt/rustwebshop; the files contain customer data, so only root may read them):

sudo mkdir -p backups && sudo chmod 700 backups
# Database
sudo docker compose exec -T db pg_dump -U shop_user shop_db | gzip | sudo tee backups/shop-$(date +%F).sql.gz > /dev/null
# Uploaded images and files
sudo docker run --rm -v rustwebshop_uploads_data:/data -v "$PWD/backups":/out alpine tar czf /out/uploads-$(date +%F).tar.gz -C /data .
sudo chmod 600 backups/*

(With Podman: sudo docker-compose and sudo podman run instead.) The updater also saves the database to backups/pre-update-….sql before every update and keeps the last 10.

Restore a database dump:

docker compose stop backend
gunzip -c backups/shop-YYYY-MM-DD.sql.gz | docker compose exec -T db psql -U shop_user -d shop_db
docker compose start backend

Copy the backups/ folder to another machine regularly. The admin's Export & Backups tab additionally exports the store settings and catalogue as JSON (importable into another installation; passwords and API keys are not included and must be entered again) and the media library as ZIP.

---

Good to know

• Where are the backups stored? As release files in your GitHub repository. They do not make the repository itself bigger, and GitHub accepts files up to 2 GB per backup.
• Who can see them? Only you and people you invite to the private repository. The token in the shop can only access this one repository. And even they only see encrypted files: reading a backup needs your private key.
• Data protection (GDPR): the backups contain personal data of your customers and are stored at GitHub, encrypted with a key only you hold. Mention GitHub as a storage provider in your privacy policy.
• Lost the private key? Then the encrypted backups can't be opened by anyone, including you. Create a new key pair right away and make a new backup (see Changing the encryption key).
• Disconnect: Disconnect in the admin stops the automatic backups and deletes the token from the shop. Backups already on GitHub stay there until you delete them (or the whole repository).
• Manual backups are still possible on the server (see manual backups above), and the admin's Export & Backups tab can additionally export the catalogue as JSON and the media library as ZIP.