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 ASSET_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 and Livewire assets after .env changes (required when ASSET_URL changes):

sh scripts/build-assets.sh

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)

The commands below are for the production profile (docker-compose.prod.yml and .env.production). For the bind-mounted development profile, rebuild with make docker-init only when you intentionally want a development environment.

1. Update source code and review configuration changes:

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

Compare .env.production with .env.production.example, without replacing the existing application key or secrets.

2. Put the current application in maintenance mode and build the new images:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan down
make build-prod

3. Start the new application container and run migrations:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml up -d mysql redis laravel
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan migrate:status
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan migrate --force

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. Refresh caches and recreate nginx and queue workers. Composer dependencies and frontend assets are already included in the production images:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan optimize
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml up -d --force-recreate nginx supervisord

6. Validate, then return the application to service:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan locales:audit
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan up
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml ps

Environment variables

For Apache/nginx, compare .env with .env.example. For production Docker, compare .env.production with .env.production.example. Follow UPGRADES_NOTES.md for variables whose value or meaning changed; 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.