Deployment

Deployment

This page gives production-oriented deployment patterns. For install commands, start with Installation.

Recommended self-hosted shape

For most servers:

1. Run Docker or a native service.
2. Persist the data directory.
3. Put the app behind HTTPS.
4. Create the first owner.
5. Configure a durable backup destination.
6. Run and verify a backup.
7. Schedule recurring backups.
8. Practice restore against a non-production deployment.

Docker service

Docker is the recommended path for normal self-hosting.

docker run -d \
  --name convex-autobackup \
  --restart unless-stopped \
  -p 8976:8976 \
  -v convex-autobackup-data:/data \
  -e CONVEX_AUTOBACKUP_MASTER_KEY="$(openssl rand -base64 32)" \
  kodydoty/convex-autobackup:latest

Open:

http://localhost:8976

Docker Compose

services:
  convex-autobackup:
    image: kodydoty/convex-autobackup:latest
    restart: unless-stopped
    ports:
      - "8976:8976"
    environment:
      CONVEX_AUTOBACKUP_MASTER_KEY: "${CONVEX_AUTOBACKUP_MASTER_KEY}"
    volumes:
      - convex-autobackup-data:/data

volumes:
  convex-autobackup-data:

Start:

CONVEX_AUTOBACKUP_MASTER_KEY="$(openssl rand -base64 32)" docker compose up -d

Store the generated master key somewhere safe before rotating shells or servers.

Native service

Download the release bundle for your platform:

https://github.com/KodyDennon/ConvexAutoBackup/releases/tag/v0.1.0-beta.5

Run:

convex-autobackup supervise

The supervised process runs the web/API server and scheduler worker together. Advanced operators may run the worker separately:

convex-autobackup serve --bind 0.0.0.0:8976
convex-autobackup-worker --data-dir /data run --poll-seconds 30

systemd example

[Unit]
Description=ConvexAutoBackup
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/convex-autobackup/env
ExecStart=/usr/local/bin/convex-autobackup supervise
Restart=always
RestartSec=5
User=convex-autobackup
Group=convex-autobackup

[Install]
WantedBy=multi-user.target

Environment file:

CONVEX_AUTOBACKUP_MASTER_KEY=...

Reverse proxy

Production installs should use HTTPS. Example nginx shape:

server {
  listen 443 ssl http2;
  server_name backups.example.com;

  location / {
    proxy_pass http://127.0.0.1:8976;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Keep the app bound to a private interface or firewall it so only the proxy can reach it.

Upgrade procedure

1. Record the currently running version.
2. Back up the ConvexAutoBackup data directory.
3. Pull the new image or install the new native bundle.
4. Restart the service.
5. Confirm GET /api/v1/health.
6. Open the UI and confirm sign-in, setup inventory, and recent runs still load.
7. Run a manual backup.
8. Verify that backup.

Rollback

1. Stop the service.
2. Restore the previous image or binary.
3. Restore the previous data directory if the new version migrated state incompatibly.
4. Start the service.
5. Confirm health and run history.

Repository docs

Versioned deployment docs live here:

https://github.com/KodyDennon/ConvexAutoBackup/blob/main/docs/DEPLOYMENT.md