Viewer guide

Backups and disk space

What to copy so a backup actually restores, and the one thing nothing cleans up: every build you ever ran stays on disk.

Everything the Viewer keeps lives under VIEWER_DATA_DIR (/data in the container; see the data volume). Back up that whole folder, and watch how big it gets.

Backups#

The database runs in WAL mode (write-ahead logging). Recent writes may live in viewer.db-wal and not yet be inside viewer.db.

Warning Copying viewer.db on its own can lose recent comments, projects and sessions, and can produce a file that will not open. Back up the whole VIEWER_DATA_DIR, including the -wal and -shm sidecars.

The simple, always-correct procedure is to stop the process first:

docker stop desde-viewer
tar czf viewer-backup-$(date +%F).tar.gz -C /var/lib/docker/volumes/desde-viewer-data/_data .
docker start desde-viewer

Note /var/lib/docker/volumes/<name>/_data is where a named volume lives on a Linux Docker Engine host. On Docker Desktop the volume is inside a virtual machine and that path does not exist on your Mac or Windows filesystem. Ask Docker where it is with docker volume inspect desde-viewer-data, or copy the data out through a throwaway container instead.

If you cannot take downtime and you have the sqlite3 command-line tool on the host (the Viewer does not ship it: storage uses Node's built-in node:sqlite), sqlite3 /data/viewer.db ".backup /path/to/viewer-backup.db" takes a consistent online copy of the database. Back up assets/ separately with a plain file copy; asset files are written once and never rewritten, so copying them while the process runs is safe.

To restore, stop the process, replace the contents of VIEWER_DATA_DIR, and start it again.

Disk growth#

Each successful build publishes its output under <VIEWER_DATA_DIR>/assets/<deploymentId>/, up to a 200 MB cap per deployment. A build that exceeds the cap fails rather than publishing a partial deployment.

Nothing prunes old deployments. There is no retention policy and no API to delete a deployment. Every build you ever run stays on disk until you remove it by hand. A project rebuilt daily accumulates a full copy of its build output every day.

Serving only ever reads a project's active deployment, so removing the asset directory of any non-active deployment is safe for the live prototype. To find out which ones those are, list your projects and note each activeDeploymentId:

curl -H "Authorization: Bearer dsv_your_token_here" http://localhost:3100/api/v1/projects

Then remove the asset directories you do not need:

rm -rf /var/lib/docker/volumes/desde-viewer-data/_data/assets/<deploymentId>

The deployment's row stays in SQLite, so it still appears in the project's deployment history with its build log. Only its files are gone. That deployment can no longer be re-activated and served.

Warning Never remove the directory named by a project's activeDeploymentId. The prototype stops loading, and the only recovery is another build.

Watch du -sh on the assets directory as part of whatever monitoring you already run. There is no disk-usage warning inside the product.