Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

3.8 KB
Raw Blame

Configuration Migrations

This directory contains configuration migration scripts for ODS.

Purpose

When ODS is updated between versions, configuration files (.env, docker-compose.yml) may need changes. Migration scripts ensure user configs are updated safely and automatically.

How It Works

  1. Version Tracking: The system tracks which migrations have run using .migration-state file
  2. Automatic Detection: migrate-config.sh check compares current version vs last migrated
  3. Safe Migration: Each migration creates a backup before making changes
  4. Incremental: Migrations run in order (v0.1.0 → v0.2.0 → v0.3.0)

Both check and migrate select scripts newer than .migration-state and no newer than the installation's .version. A newer script bundle can therefore inspect an older installation without applying future configuration changes. An upgrade to that later version makes its scripts eligible. Downgrades do not run forward migrations or roll configuration back; use the saved backup for configuration recovery.

Usage

# Check if migration needed
cd ods
./scripts/migrate-config.sh check

# Show what changed
./scripts/migrate-config.sh diff

# Run migrations (with automatic backup)
./scripts/migrate-config.sh migrate

# Manual backup
./scripts/migrate-config.sh backup

Creating New Migrations

  1. Create a new file: migrations/migrate-vX.Y.Z.sh
  2. Make it executable: chmod +x migrations/migrate-vX.Y.Z.sh
  3. Follow this template:
#!/bin/bash
# Migration: vA.B.C → vX.Y.Z
# Description: What this migration does
# Date: YYYY-MM-DD

set -e

echo "Migrating configuration to vX.Y.Z..."

# Your migration logic here
# - Add new env vars
# - Rename old vars
# - Update file formats
# etc.

echo "Migration vX.Y.Z complete"

Migration Guidelines

DO:

  • Always use set -e to fail on errors
  • Check if changes are needed before making them
  • Add comments explaining what changed
  • Test migrations on a clean environment

DON'T:

  • Delete user data
  • Change working configurations without backup
  • Assume files exist (check first)
  • Make breaking changes without warning

Integration with Updates

The ods-update.sh script automatically runs migrations during updates:

# In ods-update.sh
cd ods
./scripts/migrate-config.sh migrate || {
    echo "Config migration failed"
    exit 1
}

Troubleshooting

"Migration already applied"

  • Check .migration-state file in data directory
  • Delete it to re-run migrations (use with caution)

"Migration failed"

  • Check the backup in ~/.ods/backups/
  • Restore manually if needed
  • Review migration script for errors

Missing environment variables after update

  • Run ./scripts/migrate-config.sh diff to see what's new
  • Run ./scripts/migrate-config.sh migrate to add them

Examples

Adding a new environment variable

#!/bin/bash
ENV_FILE="${INSTALL_DIR}/.env"

if [[ -f "$ENV_FILE" ]]; then
    if ! grep -q "^NEW_VAR=" "$ENV_FILE"; then
        echo "" >> "$ENV_FILE"
        echo "# New feature configuration (v0.3.0+)" >> "$ENV_FILE"
        echo "NEW_VAR=default_value" >> "$ENV_FILE"
    fi
fi

Renaming an environment variable

#!/bin/bash
ENV_FILE="${INSTALL_DIR}/.env"

if [[ -f "$ENV_FILE" ]]; then
    # Check if old var exists
    if grep -q "^OLD_VAR=" "$ENV_FILE"; then
        # Get old value
        OLD_VALUE=$(grep "^OLD_VAR=" "$ENV_FILE" | cut -d= -f2)
        # Add new var
        echo "NEW_VAR=$OLD_VALUE" >> "$ENV_FILE"
        # Comment out old var
        sed -i 's/^OLD_VAR=/# OLD_VAR= (renamed to NEW_VAR in v0.3.0)/' "$ENV_FILE"
    fi
fi

See Also

  • ../scripts/migrate-config.sh — Migration manager
  • ../scripts/ods-update.sh — Update system that calls migrations
  • ../../docs/SHIP-PUNCH-LIST.md — Item #14 (config migration story)