Upgrade Guide¶

Upgrade procedure for Repod running under Docker Compose.

Back up before upgrading

Always run a backup before upgrading. See Backup & restore →

Before you start¶

Check the changelog for breaking changes: Changelog →
Review migration notes in the release notes for the target version.
Schedule a maintenance window — the upgrade causes ~30 seconds of downtime while containers restart.

Standard upgrade procedure¶

cd /opt/repod

# Step 1 — Back up data
./backup.sh

# Step 2 — Fetch the new version
git fetch origin
git pull origin main

# Step 3 — Stop the services
docker compose down

# Step 4 — Rebuild images
docker compose build --no-cache

# Step 5 — Start the services
docker compose up -d

# Step 6 — Verify startup
docker compose ps
curl http://localhost:8000/health/live

Verify the deployed version¶

curl -s http://localhost:8000/health/live | jq .version
# or: Settings → About in the web UI

Upgrade to a specific version¶

# List available tags
git tag -l | sort -V | tail -10

# Check out the target version
git checkout v1.3.0

# Rebuild and restart
docker compose down
docker compose build --no-cache
docker compose up -d

Rolling back¶

If a problem is discovered after upgrading:

cd /opt/repod

# 1. Stop the services
docker compose down

# 2. Return to the previous version
git log --oneline -10
git checkout <previous-tag-or-commit>

# 3. Rebuild and restart
docker compose build --no-cache
docker compose up -d

# 4. Verify
docker compose ps
curl http://localhost:8000/health/live

Database migrations

Repod uses SQLite with automatic schema migrations. Downgrading to a version that does not understand the new schema is safe as long as no new columns were written to by the newer version. If the rollback fails to start, restore the repos/auth/ and repos/package-index/ directories from your backup.

Upgrading environment variables¶

When a new version introduces new environment variables:

Check the release notes for new or changed variables.
Review the Environment variables reference →.
Update backend.env and/or .env before rebuilding:

# Compare your current backend.env to the example
diff backend.env backend.env.example

# Add any new variables with their default values
nano backend.env

Rebuilding the frontend after URL changes¶

If REACT_APP_API_URL or REACT_APP_REPO_URL changed in .env:

docker compose build frontend-ui
docker compose up -d frontend-ui

React variables are baked into the JavaScript bundle at build time — they do not take effect until the image is rebuilt.

Database migrations¶

Repod applies SQLite schema migrations automatically on startup via alembic. No manual steps are required under normal circumstances.

Verify migrations applied correctly:

docker compose logs backend-api | grep -i "alembic\|migration\|migrate"
# Expected: "Running upgrade ... OK" for each pending migration

If migrations fail:

# Check migration history
docker exec backend-api alembic history

# Check current revision
docker exec backend-api alembic current

# Force a specific revision (use only as a last resort)
docker exec backend-api alembic upgrade head

ClamAV and Grype database updates¶

ClamAV and Grype vulnerability databases are updated automatically — no upgrade action is required. If you want to force an immediate update after an upgrade:

TOKEN=$(curl -s -X POST http://localhost:8000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword!"}' | jq -r .access_token)

# Force ClamAV update
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/security/clamav/update

# Grype updates automatically on the next scan (or on startup if > 24h)
docker exec backend-api grype db update

Version-specific migration notes¶

v1.x → v2.x (planned)¶

Redis is required for JWT token revocation (optional in v1.x).
REDIS_URL environment variable must be added to backend.env.
Run docker compose build --no-cache — the base image changes.

v1.1.x → v1.2.x¶

No breaking changes. Run the standard upgrade procedure.

v1.0.x → v1.1.x¶

New environment variable: GRYPE_DB_CACHE_DIR (default: /repos/grype-db). Add to backend.env if you have custom storage paths.
The /repos/grype-db/ directory is created automatically on first startup.