ADconsle/docs/upgrading.md

Upgrading

Versioning

From v1.0.0 on, releases are semantic git tags vX.Y.Z:

• MAJOR — incompatible change: a required new .env key, a schema change that is not auto-migrated, or a new AD permission the service account needs. Read this page before upgrading.
• MINOR — new, backwards-compatible feature. Safe to pull; still run php artisan migrate.
• PATCH — backwards-compatible fix only.

The latest tag on main is the supported version; there are no long-term-support branches. Per-version notes are under Version notes below and in CHANGELOG.md.

General procedure

# back up the DB first (panel_settings + panel_attributes hold your config)
mysqldump adconsole > adconsole-$(date +%F).sql

git pull            # or fetch a new release
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan optimize          # config + route + view + event cache

Docker (from the repo root): bump ADCONSOLE_VERSION in .env, then docker compose --env-file .env -f docker/compose.yaml pull and … up -d. The entrypoint runs migrate --force and optimize for you.

Roll back = restore the DB dump and either check out the previous revision or set ADCONSOLE_VERSION back to the previous tag.

Version notes

v1.1.0 — Docker layout

The Docker files moved and the production image changed shape. One-time steps for an existing Docker install:

1. git pull — docker/compose.yaml now lives in docker/, builds a self-contained image, and reads persistent state from docker/data/ bind mounts instead of the adconsole_db_data / adconsole_app_storage named volumes.

2. Stop the old stack: docker compose -f docker/compose.yaml down (old file).

3. Copy the volume contents into docker/data/ before the first new up:

   mkdir -p docker/data/db docker/data/app_storage
   docker run --rm -v adconsole_db_data:/from -v "$PWD/docker/data/db":/to \
     alpine cp -a /from/. /to/
   docker run --rm -v adconsole_app_storage:/from -v "$PWD/docker/data/app_storage":/to \
     alpine cp -a /from/. /to/
   

4. Start it, always from the repo root and with --env-file .env:

   docker compose --env-file .env -f docker/compose.yaml up -d
   

   (export COMPOSE_FILE=docker/compose.yaml COMPOSE_ENV_FILES=.env once to drop the flags.) up -d now pulls the released image; add --build to build from the working tree.

Rootless Docker can't chown a bind-mounted MariaDB datadir — run the daemon rootful, or switch the mariadb volume in docker/compose.yaml to a named volume. Nothing changes for a bare-metal install.

Panel configuration moved into the database

Two migrations, both automatic — just run php artisan migrate (the Docker entrypoint does this for you).

1. create_panel_settings_table — general settings (password policy & generator, reset-dialog defaults, encryption key) move out of the old storage/app/panel_settings.json. The migration imports that file if present and renames it panel_settings.json.migrated.
2. create_panel_attributes_table — the AD attribute / column definitions move from the JSON blob into their own table, one row per attribute with real columns (key, label, ldap, category, type, is_column, position). The migration copies the existing list across and strips the now-unused attributes (and dead domains / users_table) keys from the panel_settings row.

• After migrating, open /settings and confirm the General tab and the Attributes tab still show your settings, then delete any storage/app/panel_settings.json.migrated.
• Fresh installs have empty tables and run on PanelSettingsService::defaults() / defaultAttributes() until you save something.
• The legacy file and its .migrated rename are git-ignored.

New .env keys

LDAP_SSL, LDAP_TLS_VERIFY, APP_DOMAIN. Existing installs keep working with the defaults (LDAP_SSL=true, LDAP_TLS_VERIFY=false); add explicit values when you next edit .env. See configuration.md.

After any upgrade

• php artisan test if you carry local patches.
• Re-check the hardening checklist.
• Watch storage/logs/laravel.log on the first real use.