Upgrade OpenDataBio

Use this guide to upgrade an existing OpenDataBio installation with minimal downtime.

Before you start

1. Read the target release notes and confirm any breaking changes.
2. Back up at least:
   • Database dump
   • .env
   • storage/app/public/media
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. Rebuild frontend assets after .env changes (required when assets_url changes):

npm run build

5. Refresh caches, clean logs, and restart workers:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart
systemctl restart supervisor.service, nginx+phpfpm or apache, mysql or mariadb
echo "" > storage/logs/laravel.log
echo "" > storage/logs/supervisor.log

6. Bring app 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. Rebuild frontend assets after .env changes (required when assets_url changes):

npm run build

5. Refresh caches and restart workers:

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

Environment variables

If the target version introduces new environment variables, compare .env with .env.example and add missing keys before asset/cache/worker commands in production.

Rollback strategy

If something fails after migration:

1. Keep maintenance mode on.
2. Restore database backup and .env.
3. Checkout the previous known-good tag.
4. Rebuild dependencies/containers and validate logs before php artisan up.