# Upgrading

## Versioning

From `v1.0.0` on, releases are [semantic](https://semver.org/) 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](#version-notes) below and
in [`CHANGELOG.md`](CHANGELOG.md).

## General procedure

```sh
# 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`:

   ```sh
   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`:

   ```sh
   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](configuration.md).

## After any upgrade

- `php artisan test` if you carry local patches.
- Re-check the [hardening checklist](deployment.md#hardening-checklist).
- Watch `storage/logs/laravel.log` on the first real use.