Backup & migration

There is one file

Everything monoki knows lives in monoki.db inside the state directory: accounts, groups, bookmarks, the icon images themselves, sharing grants, and the audit log.

That is the whole reason icons are stored as blobs in SQLite rather than as files on disk — one artifact to back up, with no chance of the database and an image directory drifting out of sync.

/var/lib/monoki/
├── monoki.db
├── monoki.db-wal
└── monoki.db-shm

Backing up

monoki runs SQLite in WAL mode, so copying monoki.db while the server is running can capture a torn state. Use SQLite's own backup, which is consistent and does not require stopping anything:

sqlite3 /var/lib/monoki/monoki.db ".backup '/backups/monoki-$(date +%F).db'"

Or stop the service and copy all three files together.

A gzipped backup of a few hundred bookmarks is well under a megabyte, so daily is entirely reasonable:

# /etc/cron.daily/monoki-backup
#!/bin/sh
set -eu
sqlite3 /var/lib/monoki/monoki.db ".backup '/backups/monoki.db.tmp'"
gzip -c /backups/monoki.db.tmp > "/backups/monoki-$(date +%F).db.gz"
rm -f /backups/monoki.db.tmp
find /backups -name 'monoki-*.db.gz' -mtime +30 -delete

Restoring

Stop monoki, put the file back, start it:

systemctl stop monoki
gunzip -c /backups/monoki-2026-08-01.db.gz > /var/lib/monoki/monoki.db
rm -f /var/lib/monoki/monoki.db-wal /var/lib/monoki/monoki.db-shm
systemctl start monoki

Delete the -wal and -shm files: they belong to the database you just replaced, and leaving them beside a different one is how you get corruption.

Moving to another machine

Copy the binary and the database. Nothing is tied to the host — no machine id, no absolute paths inside the database, no key file living somewhere else.

systemctl stop monoki
scp /var/lib/monoki/monoki.db newhost:/var/lib/monoki/

Upgrading

Replace the binary and restart. Schema migrations run automatically at startup, inside a transaction, and are recorded so they never run twice.

Migrations are forward-only: there is no downgrade path. Take a backup before upgrading, which is the actual rollback.

Reading the database directly

It is ordinary SQLite, and nothing is encrypted at rest:

sqlite3 /var/lib/monoki/monoki.db \
  "SELECT g.name, b.title, b.url
     FROM bookmarks b JOIN bookmark_groups g ON g.id = b.group_id
    ORDER BY g.position, b.position;"

That is a convenient way to export your links if you ever want to leave — which is a property worth having, not a gap.