Backups de un zerosoft self-hosted que se pueden restaurar
En zerosoft, el backup es "un archivo". Es casi cierto: una base SQLite en la que se está escribiendo no se puede copiar con cp y confiar en que la copia sirva.
Esta es la versión práctica: qué backupear, cómo copiarlo de forma consistente con la app corriendo, adónde mandarlo y cómo saber que el backup realmente se restaura. Quince minutos de setup, diez minutos por trimestre.
Qué estás backupeando
Un zerosoft self-hosted con Docker tiene exactamente tres cosas que importan:
- La base de datos. Un archivo SQLite,
zerosoftware.db, en/app/datadentro del contenedor, guardado en el volumenzerosoft-data. Links, clicks, contactos, deals, issues, reservas, conversaciones, docs, usuarios, teams, API keys: todo. - Uploads. Los adjuntos de Chat, Track y las tareas del CRM, en
/app/public/uploads, guardados en el volumenzerosoft-uploads. - Tu
.env. Fácil de olvidar, y pesa más de lo que parece. Más abajo explicamos por qué.
Sin Docker es la misma idea: data/zerosoftware.db y public/uploads/ en el directorio de la app.
Un detalle de Docker primero: Compose les antepone el nombre del proyecto a los volúmenes, y ese nombre por defecto es el del directorio. Si clonaste en zerosoft/, tus volúmenes probablemente se llamen zerosoft_zerosoft-data y zerosoft_zerosoft-uploads. Fijate en vez de adivinar:
docker volume ls | grep zerosoft
Por qué un cp no alcanza
zerosoft abre su base local en modo WAL (PRAGMA journal_mode = WAL). En modo WAL, las escrituras nuevas van primero a un archivo aparte, zerosoftware.db-wal, y se vuelcan al archivo principal más tarde, en un checkpoint. Con la app corriendo, normalmente vas a ver tres archivos: zerosoftware.db, -wal y -shm.
Entonces, si hacés cp zerosoftware.db con la app corriendo:
- Datos ya commiteados pueden seguir viviendo en el
-wal, y tu copia no los tiene. - Si copiás el
.dby el-walpor separado, puede caer una escritura en el medio y el par que te queda puede no coincidir.
Copiar a mano sí está bien si la app está frenada: en un apagado limpio SQLite hace el checkpoint del WAL al archivo principal. Si en cambio el proceso se cortó de golpe, puede quedar un -wal con datos commiteados, así que copiá todos los archivos juntos. Pero frenar tu app todas las noches para backupearla no tiene sentido cuando SQLite tiene una forma correcta de hacerlo en caliente.
La forma correcta: .backup o VACUUM INTO
SQLite trae dos formas de sacar un snapshot consistente de una base viva:
.backup(el backup online del CLIsqlite3) copia la base página por página a un archivo nuevo y produce un snapshot consistente aunque la app siga escribiendo.VACUUM INTO '/ruta/archivo.db'escribe una copia nueva y compactada de la base tal como estaba en una única transacción. Trabaja un poco más y te da un archivo más chico. El archivo destino no tiene que existir.
Las dos son correctas. Las dos incluyen lo que está en el WAL. La imagen de zerosoft no trae el CLI sqlite3, así que lo más simple es un contenedor Alpine descartable que monte el volumen:
#!/bin/sh
# /usr/local/bin/zerosoft-backup.sh
set -eu
DATA_VOL=zerosoft_zerosoft-data # verificar con: docker volume ls
UPLOADS_VOL=zerosoft_zerosoft-uploads
DEST=/var/backups/zerosoft
STAMP=$(date +%Y-%m-%d_%H%M)
mkdir -p "$DEST"
# 1. Snapshot consistente de la base viva (seguro con la app corriendo)
docker run --rm -v "$DATA_VOL":/data -v "$DEST":/backup alpine:3.20 \
sh -c "apk add --no-cache sqlite >/dev/null && sqlite3 /data/zerosoftware.db \".backup '/backup/db-$STAMP.db'\""
# 2. Verificar la copia antes de confiar en ella
docker run --rm -v "$DEST":/backup alpine:3.20 \
sh -c "apk add --no-cache sqlite >/dev/null && sqlite3 /backup/db-$STAMP.db 'PRAGMA integrity_check;'" | grep -qx ok
# 3. Los uploads son archivos comunes: tar alcanza
docker run --rm -v "$UPLOADS_VOL":/uploads:ro -v "$DEST":/backup alpine:3.20 \
tar czf "/backup/uploads-$STAMP.tgz" -C /uploads .
# 4. Guardar dos semanas en local
find "$DEST" -type f -mtime +14 -delete
Corrélo desde cron, a una hora tranquila:
# crontab -e
15 3 * * * /usr/local/bin/zerosoft-backup.sh >> /var/log/zerosoft-backup.log 2>&1
¿Preferís VACUUM INTO? Cambiá la línea de .backup por sqlite3 /data/zerosoftware.db \"VACUUM INTO '/backup/db-$STAMP.db'\".
No te olvides del .env
zerosoft cifra en la base los tokens OAuth (las integraciones de Gmail y Google Calendar) y los secretos de los webhooks con AES-256-GCM. La clave sale de ENCRYPTION_KEY, o de NEXTAUTH_SECRET si esa no está.
Qué significa para los backups: si restaurás la base en un servidor con un secreto distinto, todo carga igual, pero esos valores cifrados no se pueden descifrar. Hay que reconectar las integraciones y se pierden los secretos de firma de los webhooks. Backupeá también tu .env, por separado y cifrado (tiene tu client secret de Google), en tu gestor de contraseñas o tu bóveda de secretos. No como un archivo plano al lado de los dumps de la base.
Sacalo del servidor
Un backup en el mismo disco que la base te protege de errores, no de un disco muerto ni de un VPS borrado. Mandá la carpeta de backups a otro lado. Sirve cualquier herramienta; dos comunes:
# rclone: copiar a cualquier bucket compatible con S3 configurado como "offsite"
rclone copy /var/backups/zerosoft offsite:zerosoft-backups
# o restic: snapshots cifrados y deduplicados
restic -r s3:https://<endpoint>/<bucket> backup /var/backups/zerosoft
Sumá esa línea al final del script. Guardá más retención afuera que en local: unas semanas de diarios más algunos mensuales alcanzan para la mayoría de los equipos chicos. Y si tu storage lo permite, que las credenciales del servidor puedan escribir backups pero no borrar los viejos; al ransomware le encanta un backup que puede borrar.
Si querés algo más cercano a continuo, Litestream manda los cambios del WAL de SQLite a object storage. Lo mencionamos porque encaja bien con SQLite, pero no lo validamos específicamente con zerosoft: probá el restore antes de depender de él.
Restaurar, de verdad
El procedimiento de restore, con la app frenada:
docker compose stop
docker run --rm -v zerosoft_zerosoft-data:/data -v /var/backups/zerosoft:/backup alpine:3.20 \
sh -c "rm -f /data/zerosoftware.db-wal /data/zerosoftware.db-shm \
&& cp /backup/db-2026-10-12_0315.db /data/zerosoftware.db \
&& chown 1001 /data/zerosoftware.db"
docker run --rm -v zerosoft_zerosoft-uploads:/uploads -v /var/backups/zerosoft:/backup alpine:3.20 \
sh -c "tar xzf /backup/uploads-2026-10-12_0315.tgz -C /uploads && chown -R 1001 /uploads"
docker compose start
Dos detalles que muerden:
- Borrá el
-waly el-shmviejos. Un WAL sobrante de la base anterior nunca tiene que aplicarse encima del archivo restaurado. - El dueño de los archivos. La app corre como el usuario
zerosoft(uid 1001). Archivos restaurados como root pueden ser legibles pero no escribibles, y la app va a fallar en la primera escritura.
Las migraciones corren solas cuando arranca la app, así que restaurar un backup viejo sobre una versión más nueva de zerosoft actualiza su esquema. La dirección contraria, una base más nueva sobre código más viejo, no es algo con lo que puedas contar.
El simulacro que nadie hace
Un backup que nunca restauraste es una esperanza, no un backup. Una vez por trimestre, agarrá la última copia offsite (no la local) y revisala en algún lugar que no sea producción:
sqlite3 db-2026-10-12_0315.db "PRAGMA integrity_check;"
sqlite3 db-2026-10-12_0315.db "SELECT count(*) FROM links; SELECT count(*) FROM crm_contacts; SELECT count(*) FROM track_issues;"
¿Los números se parecen a los reales? ¿El tarball de uploads abre? Mejor todavía: una vez por año, hacé el restore completo de arriba en un VPS de repuesto con tu .env backupeado, entrá y navegá un rato. Tomá el tiempo. Ese número es tu tiempo real de recuperación, y conviene conocerlo antes de necesitarlo.
Si usás Turso
Configurá TURSO_DATABASE_URL y TURSO_AUTH_TOKEN y la base ya no está en tu servidor: es una base libSQL remota, que es sobre lo que corre nuestra propia nube. Turso tiene sus propias funciones de backup y restore; fijate qué incluye tu plan. Igual nosotros guardaríamos una copia que controlemos:
turso db shell <your-db> .dump > zerosoft-$(date +%F).sql
Los uploads siguen siendo tuyos para backupear en cualquier caso (en tu disco, o en Vercel Blob si configurás BLOB_READ_WRITE_TOKEN).
Checklist
- Snapshot de la base con
.backupoVACUUM INTO, nunca uncpa ciegas de una base corriendo. - Chequeo de integridad en cada copia.
- Tarball de uploads.
.envguardado aparte y cifrado.- Copia offsite, con retención.
- Un simulacro de restore en el calendario.
Ese es todo el runbook. Es corto porque la arquitectura es chica: un proceso, un archivo. Lo único difícil es hacer el simulacro.