Skip to content

Updating openLogForge - Bare-Metal

This guide covers how to safely update an existing bare-metal deployment of openLogForge to a new version.

Back up your data before updating

Always create a database backup before pulling a new version. See Step 1 below.

Step 1 - Back up the database

The database is a single SQLite file stored in /var/lib/openlogforge/.

sudo -u olf cp /var/lib/openlogforge/openlogforge.db \
  /var/lib/openlogforge/openlogforge-$(date +%Y%m%d-%H%M%S).db

echo "Backup complete:"
ls -lh /var/lib/openlogforge/

Move the backup to a location outside the application directory for safekeeping:

mkdir -p ~/openlogforge-backups
sudo cp /var/lib/openlogforge/openlogforge-*.db ~/openlogforge-backups/
sudo chown $USER ~/openlogforge-backups/*.db

Step 2 - Check the current version

git -C /opt/openlogforge/app describe --tags --abbrev=0

Note this version so you can roll back to it if needed.

Step 3 - Stop the backend service

sudo systemctl stop openlogforge

Caddy can stay running throughout the update - it will return a 502 while the backend is down, which is expected and brief.

Step 4 - Pull the latest code

sudo -u olf git -C /opt/openlogforge/app pull

Review what changed before applying the update:

git -C /opt/openlogforge/app log --oneline ORIG_HEAD..HEAD

Check CHANGELOG.md for breaking changes or manual migration steps:

git -C /opt/openlogforge/app diff ORIG_HEAD..HEAD -- CHANGELOG.md

Step 5 - Update Python dependencies

sudo -u olf /opt/openlogforge/venv/bin/pip install --no-cache-dir \
  -r /opt/openlogforge/app/backend/requirements.txt

Step 6 - Run database migrations

sudo -u olf bash -c "
  cd /opt/openlogforge/app/backend &&
  OLF_DB_PATH=/var/lib/openlogforge/openlogforge.db \
  /opt/openlogforge/venv/bin/alembic upgrade head
"

If a migration fails, restore your backup from Step 1 before restarting the service.

Step 7 - Rebuild the frontend

sudo -u olf bash -c "cd /opt/openlogforge/app/frontend && npm ci && npm run build:docker"

Caddy serves the frontend files directly from disk. The new files are live as soon as the build finishes - no Caddy restart is needed.

Step 8 - Restart the backend service

sudo systemctl start openlogforge

Step 9 - Verify the update

Check the service is running:

sudo systemctl status openlogforge

Tail the logs to confirm a clean startup:

sudo journalctl -u openlogforge -f

Look for:

INFO:     Application startup complete.

Confirm the web interface loads correctly in your browser.

Rolling back

If the update causes problems, roll back to the previous version and restore the database backup.

Step 1 - Stop the backend:

sudo systemctl stop openlogforge

Step 2 - Check out the previous version tag:

# List available tags
git -C /opt/openlogforge/app tag --sort=-version:refname | head -10

# Check out the version you want to roll back to
sudo -u olf git -C /opt/openlogforge/app checkout v0.2.0   # replace with your version

Step 3 - Restore the database backup:

# Stop before restoring to avoid write conflicts
sudo -u olf cp ~/openlogforge-backups/<your-backup-file>.db \
  /var/lib/openlogforge/openlogforge.db

Step 4 - Restore Python dependencies for the old version:

sudo -u olf /opt/openlogforge/venv/bin/pip install --no-cache-dir \
  -r /opt/openlogforge/app/backend/requirements.txt

Step 5 - Rebuild the old frontend:

sudo -u olf bash -c "cd /opt/openlogforge/app/frontend && npm ci && npm run build:docker"

Step 6 - Start the backend:

sudo systemctl start openlogforge

Cleaning up old database backups

Backups accumulate in /var/lib/openlogforge/. Remove old ones once you have confirmed the update is stable:

# Keep only the 5 most recent backups
ls -t /var/lib/openlogforge/openlogforge-*.db | tail -n +6 | sudo xargs rm -f

Scheduled maintenance window

For production deployments, consider the following sequence to minimise downtime:

  1. Run the backup (Step 1) in advance - it takes seconds
  2. Schedule Steps 3-8 during a low-traffic window
  3. Open two terminals: one to run the update steps, one to tail the logs: 
    sudo journalctl -u openlogforge -f
  4. Verify the UI is responsive before closing the terminals