DocsStack & database

Backup & restore

Backup managed database dan volume aplikasi: manual atau terjadwal, retensi otomatis, salinan ke S3, dan restore.

Apa: Database, volume aplikasi, dan panel sendiri
Kapan: Manual, atau cron dengan retensi
Di mana: Volume aoox_backups + S3 opsional

Alur satu backup

01dumpcontainer sekali-jalan dari image engine, kredensial via env
02simpanfile di volume aoox_backups
03unggahrclone ke S3 bila tujuan dipilih
04prunebackup terjadwal tertua > retensi dihapus (lokal + S3)

File tidak pernah lewat proses API — dump, unggah, dan restore semuanya dilakukan container sekali-jalan. Backup manual tidak pernah dipangkas oleh retensi; hanya yang terjadwal.

Backup database

Halaman database → tab Backup.

Engine	Cara dump	Restore
PostgreSQL	`pg_dump \| gzip` (atau `pg_dumpall` untuk semua database)	Online — stream ke psql, tanpa downtime.
MySQL / MariaDB	`mysqldump` / `mariadb-dump` sebagai root	Online — stream ke mysql.
Redis	`redis-cli --rdb`	Offline — container di-stop, snapshot dipasang sebagai base AOF, lalu di-start lagi.

Backup manual

Klik Backup. Baris baru muncul dengan status, ukuran, waktu, pemicu (manual/terjadwal), penanda S3 bila tersalin (atau hanya di S3 bila file lokal sudah tidak ada), dan tombol unduh / restore / hapus.

Jadwal & tujuan

Form Jadwal & tujuan backup
Frekuensi Cron
Nonaktif —
Setiap jam 0 * * * *
Setiap hari 02:00 0 2 * * *
Setiap minggu (Minggu 03:00) 0 3 * * 0
Kustom cron 5 kolom, mis. 30 1 * * *
- Jumlah simpan — default 7; backup terjadwal tertua di luar jumlah ini dihapus setelah backup berikutnya.
- Tujuan S3 — Hanya lokal atau salah satu tujuan yang terdaftar (lihat bawah).
- Semua database di server — untuk PostgreSQL/MySQL/MariaDB dengan database tambahan: dump mencakup semuanya (PostgreSQL memakai pg_dumpall, termasuk role). Baris backup ditandai semua database.
Simpan
Jadwal langsung didaftarkan ulang tanpa restart API. Zona waktu cron = UTC.

Frekuensi	Cron
Nonaktif	`—`
Setiap jam	`0 * * * *`
Setiap hari 02:00	`0 2 * * *`
Setiap minggu (Minggu 03:00)	`0 3 * * 0`
Kustom	`cron 5 kolom, mis. 30 1 * * *`

Restore

Klik restore pada baris backup → konfirmasi
Bila file lokalnya sudah tidak ada (dipangkas retensi, disk baru) tapi salinan S3 masih ada, baris ditandai hanya di S3 — restore dan unduh tetap bisa: file ditarik kembali dari S3 otomatis lebih dulu. Untuk aplikasi di server remote, penarikan itu terjadi di daemon server tersebut.
Tunggu selesai
SQL: tanpa downtime, tapi statement DROP/CREATE di dump akan mengganti isi tabel. Redis: container berhenti sebentar.

Backup volume aplikasi

Halaman aplikasi → tab Mount → bagian Backup volume. Berlaku untuk mount jenis volume saja (bind mount belum). Bila aplikasi punya lebih dari satu volume, pilih volumenya dulu.

Aksi	Yang terjadi
Backup	busybox sekali-jalan, volume di-mount `:ro`, `tar czf` ke `<app>/<mount>/<stamp>.tar.gz`. Container aplikasi tetap jalan.
Restore	Stop container → kosongkan volume → extract → start. Ada downtime singkat.
Jadwal	Form Jadwal backup volume: frekuensi, jumlah simpan, tujuan S3 — berlaku untuk semua volume aplikasi; prune per volume.

Berlaku juga untuk aplikasi di server remote — backup, unggah/unduh S3, dan restore dijalankan di daemon server itu.
Backup saat aplikasi sedang menulis bisa menangkap file setengah jadi — jadwalkan di jam sepi.

Backup instance (panel sendiri)

Settings → Backup instance (owner) menyimpan database internal aoox: pengguna, project, aplikasi, database, jadwal, kredensial terenkripsi — semuanya sebagai satu file JSON ter-gzip di volume backup, tanpa pg_dump.

Aksi	Keterangan
Backup sekarang	Membuat snapshot langsung; muncul di daftar dengan ukuran dan waktu.
Jadwal	Cron 5 kolom + Tujuan S3 opsional, seperti backup database.
Unduh	Simpan file di luar server — inilah yang dipakai saat memasang ulang.
Restore dari file	Unggah file backup; seluruh tabel ditulis ulang dalam satu transaksi, lalu penjadwal dan sesi SSH dibangun ulang.

Yang perlu diperhatikan saat restore

File hanya bisa dipulihkan ke versi skema yang sama — restore ke versi aoox yang jauh berbeda ditolak.
ENCRYPTION_KEY harus sama dengan saat backup dibuat; bila berbeda, kredensial tersimpan tidak bisa dibaca dan aoox melaporkannya.
Ini memulihkan panel, bukan data aplikasi. Container, volume, dan image tetap urusan backup database/volume.

Kombinasi untuk pindah server: backup instance + backup database + backup volume, semuanya dengan tujuan S3. Alternatif yang lebih ringan untuk memindahkan satu project saja: export/import project.

Tujuan S3

Settings → Tujuan backup (S3) → Tujuan backup baru (owner/admin)

Field	Keterangan
Nama	Label.
Endpoint	Kosong = AWS S3. Isi untuk MinIO, Wasabi, R2, dsb. — mis. `https://minio.example.com`, atau `http://aoox-minio-…:9000` untuk MinIO yang berjalan di aoox (satu network).
Region	Wajib untuk AWS (`us-east-1`); provider lain biasanya bebas.
Bucket	Harus sudah ada — aoox tidak membuatnya.
Prefix	Opsional, mis. `aoox/prod`.
Access key ID / Secret access key	Secret hanya ditulis sekali, disimpan terenkripsi.
Path-style	Default aktif (MinIO); matikan untuk virtual-host style (AWS, R2).

Tes koneksi
Menjalankan rclone lsjson ke bucket lewat container rclone/rclone; error provider ditampilkan apa adanya.
Pilih di jadwal backup database / volume
Setiap backup (manual maupun terjadwal) yang sukses diunggah ke <prefix>/<slug>/<stamp>.<ext>. Menghapus/prune backup juga menghapus objek remote.

Gagal unggah membuat backup berstatus failed dan memicu notifikasi — file lokal tetap ada untuk diunduh. Tujuan dipasang justru supaya salinan ada di tempat lain, jadi kegagalan tidak disembunyikan.

Strategi yang disarankan

Kebutuhan	Pengaturan
Produksi kecil	Setiap hari 02:00, simpan 7, tujuan S3. Uji restore sebulan sekali ke database baru.
Data sering berubah	Setiap jam, simpan 24–48, tujuan S3.
Sebelum migrasi/impor besar	Backup manual (tidak pernah dipangkas) — beri nama di catatan tim.
Pindah server / pemulihan bencana	Backup instance + database + volume, ketiganya dengan tujuan S3; simpan juga .env.dist (JWT_SECRET & ENCRYPTION_KEY).
Aplikasi dengan upload	Backup volume harian + backup database pada jam yang sama.

Jebakan umum

Gejala	Penyebab & solusi
Backup 20 byte / kosong	Sudah ditangani (status dump dipropagasi). Bila terjadi, cek pesan error backup — biasanya kredensial atau database belum siap.
Tes tujuan S3 gagal: NoSuchBucket	Bucket belum dibuat, atau region salah (AWS).
Tes gagal ke MinIO lokal	Endpoint memakai localhost dari dalam container. Pakai nama container + port 9000, atau domain publiknya.
Restore Redis: data tidak berubah	Backup Redis 7 dipasang sebagai base AOF; pastikan container benar-benar di-start ulang (status running kembali) dan tidak ada tulisan baru sebelum restore selesai.
Volume backup penuh	Turunkan jumlah simpan, hapus backup manual lama, atau pindahkan ke S3 dan hapus lokal.

Belum tersedia

Retensi terpisah untuk objek di S3; backup bind mount; backup untuk stack compose & database di dalamnya; restore instance lintas versi skema.

Langkah berikutnya

Managed databaseDatabase yang di-backup.MountVolume aplikasi yang bisa di-backup.NotifikasiKabar saat backup gagal.TemplateMinIO dari katalog sebagai tujuan S3 lokal.

Ada yang keliru? Edit halaman ini di GitLab ↗

Backup manual

Jadwal & tujuan

Form Jadwal & tujuan backup

Simpan

Restore

Klik restore pada baris backup → konfirmasi

Tunggu selesai

Settings → Tujuan backup (S3) → Tujuan backup baru (owner/admin)

Tes koneksi

Pilih di jadwal backup database / volume