Skip to content

upgrading.md

Latest commit

 

History

History
199 lines (142 loc) · 5.05 KB

upgrading.md

File metadata and controls

199 lines (142 loc) · 5.05 KB
Raw

Upgrading RustShare

This guide helps operators upgrade a running RustShare deployment.

Project status: Pre-1.0. Breaking changes may occur on MINOR version bumps. Always review CHANGELOG.md and the Breaking Changes section before upgrading.

General Upgrade Steps

Follow this sequence for every upgrade:

  1. Create a backup

    ./scripts/backup-stack.sh

    Verify the backup bundle contains postgres.sql.gz, rustfs-data.tar.gz, config.tar.gz, and manifest.env.

  2. Review the changelog

  3. Pull the new image

    docker compose pull

    Or, if using the pilot profile:

    export RUSTSHARE_BACKEND_IMAGE=ghcr.io/kubedoio/rustshare-backend:X.Y.Z
docker compose -f docker-compose.yml -f docker-compose.pilot.yml pull

  4. Run database migrations

    • Migrations are applied automatically when the backend container starts, or
    • Run manually: 
      docker compose exec backend sqlx migrate run
    • Check backend logs for migration success: 
      docker compose logs backend --tail=50

  5. Restart services

    docker compose up -d

    Or with the pilot profile:

    docker compose -f docker-compose.yml -f docker-compose.pilot.yml up -d

  6. Verify health

    ./scripts/final-launch-smoke.sh

    Confirm all containers are running and the health endpoint responds.

Pre-1.0 Warning

RustShare is currently pre-1.0. While we adhere to SemVer:

  • MINOR bumps (e.g., 0.2.x → 0.3.0) may include breaking changes.
  • PATCH bumps (e.g., 0.2.1 → 0.2.2) should be safe.

Recommendations:

  • Pin to exact versions in production (X.Y.Z, not X.Y or X).
  • Read CHANGELOG.md and this upgrading guide before any MINOR upgrade.
  • Test MINOR upgrades in a staging environment first.

Database Migrations

RustShare uses sqlx migrations stored in backend/migrations/.

Automatic migrations

The Docker entrypoint runs sqlx migrate run on startup by default. No operator action is required unless the migration fails.

Manual migrations

If you prefer to run migrations explicitly (e.g., during a maintenance window):

docker compose exec backend sqlx migrate run

Troubleshooting

If a migration fails with a checksum mismatch:

error: migration 20260404000002 was previously applied but has been modified

See docs/DEPLOYMENT.md for the resolution procedure.

Docker Compose Upgrade

Standard stack

# 1. Backup
./scripts/backup-stack.sh

# 2. Pull new images
docker compose pull

# 3. Recreate containers with new images
docker compose up -d

# 4. Verify
./scripts/final-launch-smoke.sh

Pilot stack (pre-built image)

# 1. Backup
./scripts/backup-stack.sh

# 2. Set the target image
export RUSTSHARE_BACKEND_IMAGE=ghcr.io/kubedoio/rustshare-backend:X.Y.Z

# 3. Pull and recreate
docker compose -f docker-compose.yml -f docker-compose.pilot.yml pull
docker compose -f docker-compose.yml -f docker-compose.pilot.yml up -d

# 4. Verify
./scripts/final-launch-smoke.sh

Rollback Procedure

If an upgrade fails or causes unexpected behavior:

  1. Stop the current stack

    docker compose down

  2. Restore the previous image

    • For standard stack: rebuild from the previous Git commit.
    • For pilot stack: revert the RUSTSHARE_BACKEND_IMAGE to the previous version tag.

  3. Restart with the previous image

    docker compose up -d

    Or for pilot:

    export RUSTSHARE_BACKEND_IMAGE=ghcr.io/kubedoio/rustshare-backend:PREVIOUS_VERSION
docker compose -f docker-compose.yml -f docker-compose.pilot.yml up -d

  4. If data corruption occurred, restore from backup

    ./scripts/restore-stack.sh ./backups/YYYYMMDDTHHMMSS

    Then run the post-restore smoke test:

    ./scripts/post-restore-smoke.sh

  5. Verify rollback

    ./scripts/final-launch-smoke.sh

Breaking Changes

This section documents known breaking changes by version. Because RustShare is pre-1.0, MINOR version bumps may require operator action.

Version Breaking Change Migration Path
0.4.0 No known breaking changes. Follow the general upgrade steps and verify the deployment health check after restart.
— — —

Environment Variable Changes

This section tracks new, removed, or renamed environment variables by version.

Version Change Details
0.4.0 No changes. No new, removed, or renamed environment variables are required for this release.
— — —