Updating

This guide covers how to update your self-hosted Playlist Pipeline installation.

Before You Update

1. Check the changelog - Review the Changelog for breaking changes
2. Backup your database - Always backup before updating
3. Plan for downtime - Updates may require a brief service restart

Backup

Database Backup

# PostgreSQL backup
docker compose exec db pg_dump -U postgres plpl > backup.sql

Restore from Backup

# Restore if needed
docker compose exec -T db psql -U postgres plpl < backup.sql

Update with Docker Compose

Pull Latest Images

docker compose pull

Run Migrations

If the update includes database migrations:

docker compose exec api bun db:migrate

Restart Services

docker compose up -d

Verify

Check that all services are running:

docker compose ps

Update Process

Standard Update

For most updates:

# Pull new images
docker compose pull

# Restart with new images
docker compose up -d

# Run migrations if needed
docker compose exec api bun db:migrate

Major Version Updates

For major version updates, follow any specific migration guides in the changelog. Major updates may include:

• Database schema changes
• Configuration changes
• Breaking API changes

Rollback

If an update causes issues:

# Stop services
docker compose down

# Restore database backup
docker compose exec -T db psql -U postgres plpl < backup.sql

# Pull previous version (specify tag)
docker compose pull api:v1.0.0

# Restart
docker compose up -d

Automatic Updates

For production deployments, we recommend:

1. Staging environment - Test updates in staging first
2. Scheduled maintenance windows - Plan updates during low-traffic periods
3. Monitoring - Watch logs after updates for any issues

# Watch logs after update
docker compose logs -f

Version Pinning

To pin to a specific version instead of latest:

docker-compose.yml

services:
  api:
    image: ghcr.io/your-org/plpl-api:v1.2.3

This prevents unexpected updates when pulling images.