> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgtex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrades and Migrations

> How to safely update your self-hosted Corgtex instance.

As Corgtex evolves, you will periodically need to upgrade your self-hosted instance to receive new features, bug fixes, and security patches.

Upgrading Corgtex consists of two main steps:

1. Pulling the new Docker images (Web and Worker).
2. Applying Prisma database migrations.

## Performing an Upgrade

Use the following sequence to safely upgrade your environment.

<Steps>
  <Step title="Back up your database">
    Always perform a full `pg_dump` of your production database before applying any application updates.

    ```bash theme={null}
    pg_dump -U postgres -h localhost -d corgtex -F c -f corgtex_backup.dump
    ```
  </Step>

  <Step title="Pull the latest code">
    If building from source, pull the latest changes from the upstream `main` branch.

    ```bash theme={null}
    git pull origin main
    ```
  </Step>

  <Step title="Rebuild and deploy">
    Rebuild the Docker images and recreate the containers in detached mode.

    ```bash theme={null}
    docker compose -f docker-compose.selfhost.yml up -d --build
    ```
  </Step>

  <Step title="Verify shared services for client instances">
    Before marking a client instance upgraded, confirm the environment has its shared runtime services wired into every app runtime service.

    For Railway client projects, verify:

    * Redis exists in the same project and environment as the client app.
    * `REDIS_URL` and a client-specific `REDIS_KEY_PREFIX` are set on web and worker services.
    * A Railway bucket or another S3-compatible bucket exists for uploads.
    * `S3_ENDPOINT`, `S3_BUCKET_NAME`, `AWS_S3_BUCKET_NAME`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ACCESS_KEY`, and `S3_SECRET_KEY` are set on web and worker services.
    * Web and worker have been redeployed after variable changes.
    * The web health endpoint returns healthy and fresh logs do not include `StorageProvider: Missing S3/R2 endpoint`.

    Client deployments such as Crina should be checked independently from the main Corgtex production project. Do not assume one Railway project inherits Redis or bucket configuration from another.
  </Step>
</Steps>

## Automatic Database Migrations

You generally **do not** need to run database migrations manually.

The Corgtex Dockerfiles use an `entrypoint.sh` script that automatically runs `npx prisma migrate deploy` before starting the Next.js server or the Node worker.

This ensures that the database schema is strictly synchronized with the application code booting up in the container. If a migration fails, the container boot sequence will abort, protecting your database state.

<Warning>
  Never run `prisma db push` on a production or self-hosted deployment. Always rely on the strict migration history applied by `prisma migrate deploy`.
</Warning>