Upgrade OpenDataBio

Use this page for the common deployment sequence. Before upgrading, read UPGRADES_NOTES.md from the target version of OpenDataBio. It is the authoritative source for version-specific prerequisites, storage permissions, migrations, backfills and repair commands; those instructions are intentionally not duplicated here.

Before you start

1. Read the target version’s UPGRADES_NOTES.md and release notes. Record every required preflight check and post-migration command before starting.
2. Back up at least:
   • Database dump
   • .env
   • the complete storage/app tree, including media, generated exports and persisted dataset-version archives
3. Compare current config files against target-version templates/settings:
   • .env against .env.example (including assets_url)
   • Supervisor worker config (/etc/supervisor/conf.d/opendatabio-worker.conf or container equivalent)
   • PHP config (php.ini for CLI and FPM/Apache)
4. Plan a maintenance window for production.

Upgrade (Apache or nginx installation)

1. Put application in maintenance mode:

cd /home/odbserver/opendatabio
php artisan down

2. Update source code:

git fetch --tags
git checkout <target-tag-or-branch>

3. Install dependencies and run migrations:

composer install --no-dev --optimize-autoloader
php artisan migrate:status
php artisan migrate --force

4. Run the post-migration commands listed in the target version’s UPGRADES_NOTES.md, in the documented order. Some commands submit background UserJobs; keep the application in maintenance mode and monitor them until completion when the notes require it.
5. Rebuild frontend assets after .env changes (required when ASSET_URL changes):

npm run build

6. Refresh caches and restart workers:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart
systemctl restart supervisor.service
# Restart the web server and PHP-FPM as appropriate for your installation.

7. Verify the application, queue workers, logs and the operations named in the upgrade notes, then bring the application back online:

php artisan up

Upgrade (Docker installation)

1. Update source code:

cd opendatabio
git fetch --tags
git checkout <target-tag-or-branch>

2. Rebuild and restart containers:

make stop
make build
make start

3. Install dependencies and run migrations:

make composer-install
make migrate

4. Run the target version’s UPGRADES_NOTES.md post-migration commands inside the application container, in the documented order, and monitor any UserJobs they submit.
5. Rebuild frontend assets after .env changes (required when ASSET_URL changes):

npm run build

6. Refresh caches and restart workers:

make optimize
docker compose exec -T -u www-data laravel php artisan queue:restart

Environment variables

Compare .env with the target version’s .env.example before building assets or caching configuration. Follow UPGRADES_NOTES.md for variables whose value or meaning changed; in production, verify APP_FORCE_HTTPS and ASSET_URL.

Rollback strategy

If something fails after migration:

1. Keep maintenance mode on.
2. Restore the database, .env, and the matching storage/app backup. Database rows and persisted dataset-version archives must be restored as one snapshot.
3. Checkout the previous known-good tag.
4. Rebuild dependencies/containers and validate logs before php artisan up.