Skip to main content

Update Guide

Keep your Bellamy Book installation up to date.

Update Process​

1. Backup First​

Always backup before updating:

# Backup databases
/usr/local/bin/backup-postgres.sh
/usr/local/bin/backup-mongo.sh

# Backup files
tar -czf /backups/files_before_update.tar.gz /var/www/uploads

2. Check Release Notes​

Review release notes for breaking changes and new opt-in features:

3. Update Code​

Git Update​

cd /opt/bellamy-book
git fetch origin
git checkout main
git pull origin main

4. Update Dependencies​

Backend​

cd Src/backend
dotnet restore
dotnet build

Frontend​

cd Src/frontend
npm install
npm run build

5. Run migrations (source install only)​

If you installed from source (not the self-host kit with pre-built images), apply migrations:

cd Src/backend
dotnet ef database update --project DatabaseApplication

If you use the self-host kit (pre-built images), run the database app container instead: see Self-host kit (pre-built images) below.

6. Restart Services​

Systemd​

sudo systemctl restart bellamy-book-backend
sudo systemctl reload nginx

Docker​

# From the folder that contains docker-compose.yml
docker compose build
docker compose up -d

Docker Updates​

Self-host kit (pre-built images)​

If you deploy with the self-host kit (the folder with docker-compose.yml and pre-built images, no source code):

  1. In .env, set IMAGE_TAG to the new tag (e.g. v1.0.1) provided by the publisher.
  2. From the folder that contains docker-compose.yml:
docker compose pull
docker compose up -d
  1. The database app runs automatically on docker compose up -d. Re-run it only if the publisher instructs (e.g. after an upgrade that includes schema changes):
docker compose run --rm db-migration

No source code or dotnet ef is required.

Full project (when you have the application source)​

When you have the full Bellamy Book source and run from source or custom-built images:

From the folder where you run Docker Compose:

docker compose pull
docker compose build   # if you rebuild images
docker compose up -d

Run docker compose run --rm db-migration when release notes or the publisher say so. If you run migrations from the API container instead: docker compose exec api dotnet ef database update --project DatabaseApplication.

Version Pinning​

Pin to Specific Version​

git checkout v1.2.3

Update Strategy​

  • Patch updates: Apply immediately
  • Minor updates: Review and test, then apply
  • Major updates: Review breaking changes, test thoroughly

Rollback Procedure​

Git Rollback​

cd /opt/bellamy-book
git checkout previous-version-tag
# Rebuild and restart

Database Rollback​

If migrations need rollback:

cd Src/backend
dotnet ef database update PreviousMigration --project DatabaseApplication

Docker Rollback​

From the folder that contains docker-compose.yml:

docker compose down
# Restore from backup if needed
docker compose up -d

Testing Updates​

Staging Environment​

Test updates in staging first:

  1. Deploy to staging
  2. Run test suite
  3. Verify functionality
  4. Deploy to production

Health Checks​

After update, verify:

# Check API health
curl http://localhost:5000/health

# Check frontend
curl http://localhost:3000

# Check database connections
psql -U bellamyuser -d bellamybook -c "SELECT 1;"

Automated Updates​

Watchtower (Docker)​

Automatically update Docker containers:

services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 2 * * *

Next Steps​