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.
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
- Version Tracking: The system tracks which migrations have run using
.migration-statefile - Automatic Detection:
migrate-config.sh checkcompares current version vs last migrated - Safe Migration: Each migration creates a backup before making changes
- 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
- Create a new file:
migrations/migrate-vX.Y.Z.sh - Make it executable:
chmod +x migrations/migrate-vX.Y.Z.sh - 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 -eto 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-statefile 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 diffto see what's new - Run
./scripts/migrate-config.sh migrateto 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)