Skip to main content

How to Upgrade

This guide walks you through upgrading your self-hosted Agenta instance using Docker Compose and applying any necessary database schema migrations.

Understanding Agenta Versioning​

Agenta follows semantic versioning with new releases every week. Stay updated by:

Standard Upgrade Process​

For most upgrades, follow these steps to update your Agenta instance:

1. Pull the Latest Images​

Download the newest version of all Agenta Docker images:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml pull

2. Restart Services​

Restart all services with the updated images:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web up -d
info

This method will cause a brief downtime while services restart. For production environments, consider the zero-downtime upgrade approach below.

Zero-Downtime Upgrade​

For production environments where uptime is critical, use this approach to upgrade without service interruption.

Prerequisites​

Install docker rollout for rolling updates

Upgrade Steps​

1. Pull Latest Images

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml pull

2. Apply Database Migrations

Before updating services, apply any database schema changes:

docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core <api-container-name> alembic -c alembic.ini upgrade head

Replace <api-container-name> with your actual API container name (e.g., agenta-oss-gh-api-1).

3. Rolling Update Services

Update each service individually to maintain availability:

# Update core services one by one
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh api
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh worker
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh web
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh completion
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh chat

Each command will:

  • Scale the service to double the current instances
  • Wait for new containers to be ready
  • Remove old containers once new ones are healthy

Database Schema Migrations​

When Migrations Are Needed​

Check the release notes to see if a version requires database migrations. Not all updates require schema changes.

Manual Migration Process​

1. Find Your API Container Name

List running containers to identify your API container:

docker ps | grep api

2. Run the Migration Command

Apply all pending migrations:

docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core <api-container-name> alembic -c alembic.ini upgrade head

Command Breakdown:

  • docker exec: Runs commands inside an existing container
  • -e PYTHONPATH=/app: Sets the Python path for the application
  • -w /app/oss/databases/postgres/migrations/core: Sets the working directory to the migrations folder
  • <api-container-name>: Your actual API container name
  • alembic -c alembic.ini upgrade head: Runs all migrations to the latest version

Verifying Migrations​

After running migrations:

  1. Check Application Health: Access Agenta through your web browser
  2. Verify Data Integrity: Ensure your projects, prompts, and evaluations are intact
  3. Test Core Functions: Try creating a new prompt or running an evaluation
  4. Check Logs: Review container logs for any error messages

Migration Troubleshooting​

If you encounter issues after migration:

  1. Check Migration Status:

    docker exec <api-container-name> alembic -c alembic.ini current

  2. Review Migration History:

    docker exec <api-container-name> alembic -c alembic.ini history

  3. Rollback if Necessary:

    docker exec <api-container-name> alembic -c alembic.ini downgrade -1

  4. Report Issues: Create a GitHub issue with details about the problem

Automatic Migration Configuration​

warning

Use automatic migrations with caution in production environments. Always test migrations on staging environments first.

You can configure Agenta to run migrations automatically during container startup.

Enabling Automatic Migrations​

Add this environment variable to your .env.oss.gh file:

AGENTA_AUTO_MIGRATION=true

With this setting enabled:

  • Migrations run automatically when the API container starts
  • No manual migration commands are needed
  • Container startup may take longer while migrations run