Backup and Restore

Back up and restore the full CONFIG_DIR, mounted at /data from the p2pstream-data Docker volume in the recommended Compose setup.

Use This When

Use this before upgrades, host moves, disaster recovery tests, or any change that could replace the persistent data volume.

Prerequisites

• Shell access to the Docker host or binary install host.
• Enough storage for the SQLite database, WAL files, certificates, ACME state, and cache metadata.
• A maintenance window if you want the simplest consistent SQLite backup.

Steps

Run every Compose command from your deployment directory, with the same project name, ordered -f files, and --env-file options you normally use. Confirm the actual volume name with docker compose config --volumes and docker volume inspect; substitute it below if you changed the default.

Keep a private backup of compose.yaml, any overrides, .env, the exact repository image digest used for this backup, and any optional release receipt alongside the data archive. Record the digest even if .env uses a mutable channel such as latest or staging; the tag alone can select a newer image and run migrations during restore. These inputs are needed to restore the matching application version and settings. Protect backups as secrets: they contain credentials, private keys, and user data.

Before removing the original container or image, read its repository digests and save the matching ghcr.io/kirari04/p2pstream@sha256:… value with the backup:

container_id=$(docker compose ps -a -q p2pstream)
image_id=$(docker inspect --format '{{.Image}}' "$container_id")
docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' "$image_id"

If the image has no repository digest, retain that exact image with docker image save and reload it before restoring; do not substitute a mutable channel tag.

1. Include at least:

   /data/p2pstream.db
   /data/p2pstream.db-wal
   /data/p2pstream.db-shm
   /data/certs/

   The database stores proxy config, users, sessions, agent registry, TLS metadata, and observability. The cert directory stores management TLS and public TLS material.

2. For the safest simple Compose backup, stop the service, copy the volume, then start it again:

   docker compose stop p2pstream
   
   docker run --rm \
     -v p2pstream-data:/data:ro \
     -v "$PWD:/backup" \
     debian:bookworm-slim \
     tar -C /data -czf /backup/p2pstream-data.tar.gz .
   
   docker compose start p2pstream

3. To restore, confirm your backup is readable and stop Compose. Save any current data you may need before replacing the named volume:

   docker compose down
   docker volume rm p2pstream-data
   docker volume create p2pstream-data

4. Extract the backup into the restored volume:

   docker run --rm \
     -v p2pstream-data:/data \
     -v "$PWD:/backup" \
     debian:bookworm-slim \
     tar -C /data -xzf /backup/p2pstream-data.tar.gz

5. Restore the Compose inputs and .env saved with the backup. Set P2PSTREAM_IMAGE to the recorded repository@sha256:… digest (or the exact reloaded image if it had no repository digest), then start p2pstream with the restored volume:

   docker compose up -d

Verification

After restore:

1. Open management and confirm Overview loads.
2. Under Proxy → Listeners, confirm the expected public listeners are running.
3. Under TLS, confirm certificate mappings are ready.
4. Under Agents → Fleet, confirm enabled agents reconnect.
5. Send a test request through each important public hostname.

Troubleshooting

Symptom	Check
Agents fail TLS after restore	Restore /data/certs/management or update each agent with the new CA.
Public TLS mappings are missing	Confirm /data/certs/ and SQLite were restored together.
Login state changed	Sessions are stored in SQLite and depend on the restored database.
Cache files missing	Cache can refill; SQLite and certs are more critical than cached bodies.

Next Steps

• Upgrades
• Database reference
• Security hardening