# Configuration Reference

## Overview

All constants live in `manage-client/config.php`, copied from
`manage-client/config.sample.php`. Every constant has a default in
`manage-client/lib/client.php`; a minimal `config.php` only needs the three
connection values plus `MANAGE_BACKUP_SOURCES`.

Constants are set with `define()`, not as an array. If a constant is
already defined by the project, the project's value wins.

## Connection

| Constant | Default | Meaning |
|---|---|---|
| `MANAGE_SERVER_URL` | `""` | base URL of the Manage server, without `/api` and without a trailing slash |
| `MANAGE_INSTANCE` | `""` | instance id, as created on the server |
| `MANAGE_TOKEN` | `""` | the instance's secret token, shown once when created |
| `MANAGE_HTTP_TIMEOUT` | `15` | seconds for manifest and heartbeat |
| `MANAGE_HTTP_TIMEOUT_LONG` | `300` | seconds for package download and backup upload |

If any of the first three values is missing, every function that contacts
the server reports a configuration error. Local backups still work as long
as `MANAGE_BACKUP_UPLOAD` is `false`.

## Application layout

| Constant | Default | Meaning |
|---|---|---|
| `MANAGE_APP_ROOT` | parent directory of `manage-client/` | root of the application. Update target, base of every relative backup path |
| `MANAGE_VERSION_FILE` | `MANAGE_APP_ROOT . "/VERSION"` | file holding the installed version |
| `MANAGE_VERSION_CONSTANT` | `null` | name of the constant in that file, or `null` for a plain text file |
| `MANAGE_WORK_DIR` | `data/manage/work/` | working directory for updates, cleared after every run |
| `MANAGE_UPDATE_BACKUP_DIR` | `data/manage/updates/` | copies of the files an update overwrote |
| `MANAGE_BACKUP_DIR` | `data/manage/backups/` | local backup archives |
| `MANAGE_LOG_FILE` | `data/manage/manage-client.log` | the client's JSONL log |

### Version file

Two variants are supported.

PHP file with a constant:

```php
define("MANAGE_VERSION_FILE", MANAGE_APP_ROOT . "/includes/version.php");
define("MANAGE_VERSION_CONSTANT", "APP_VERSION");
```

Plain text file that only contains `v1.2.3`:

```php
define("MANAGE_VERSION_FILE", MANAGE_APP_ROOT . "/VERSION");
define("MANAGE_VERSION_CONSTANT", null);
```

With the constant variant, the version is read from the file with a regular
expression, and the file is **not** executed. That way reading it still
works even when the constant is already defined in the running process with
the old value — for example right after an update.

The version itself is never written by the client: it's part of the release
package and changes as a side effect of copying files.

## Update

| Constant | Default | Meaning |
|---|---|---|
| `MANAGE_UPDATE_PROTECTED_PATHS` | `["config.php", "data/", ".git/", "manage-client/config.php"]` | paths that are never overwritten |
| `MANAGE_UPDATE_SANITY_PATHS` | `["index.php"]` | the package must contain at least one of these paths |
| `MANAGE_UPDATE_POST_HOOK` | `null` | callback after a successful update |
| `MANAGE_MIGRATIONS_DIR` | `MANAGE_APP_ROOT . "/migrations"` | directory with migration scripts, `null` disables them |
| `MANAGE_MIGRATIONS_STATE` | `data/manage/migrations.json` | which migrations have already run |

Paths in `MANAGE_UPDATE_PROTECTED_PATHS` are relative to `MANAGE_APP_ROOT`.
An entry with a trailing slash protects the directory and its contents;
without a slash, the exact path is protected, but a directory is likewise
protected with its contents. `config.php` and the data directory always
belong here.

`MANAGE_UPDATE_SANITY_PATHS` prevents a completely unrelated ZIP from being
copied over the application. The value should name a file or directory that
every release contains.

The hook and migrations are described in
[07_POST_UPDATE_HOOKS](07_POST_UPDATE_HOOKS.md).

## Backup

| Constant | Default | Meaning |
|---|---|---|
| `MANAGE_BACKUP_SOURCES` | `[["as" => "data", "glob" => "data/*.json"]]` | what goes into the archive |
| `MANAGE_BACKUP_DATABASE` | `null` | optional MySQL dump |
| `MANAGE_BACKUP_LOCAL_RETENTION` | `4` | local archives kept. Minimum 1 |
| `MANAGE_BACKUP_AUTO_INTERVAL_SECONDS` | `604800` | interval for `manageBackupCreateAutomaticIfDue()`, `0` disables it |
| `MANAGE_BACKUP_COMPRESS` | `true` | compress entries in the ZIP (deflate) |
| `MANAGE_BACKUP_UPLOAD` | `true` | send every new backup to the Manage server |
| `MANAGE_BACKUP_REMOTE_TARGETS` | `[]` | extra targets: `s3`, `sftp`, `custom` |

Layout of sources and targets: [05_BACKUP_SOURCES](05_BACKUP_SOURCES.md).

`MANAGE_BACKUP_COMPRESS` needs zlib, which is present in PHP by default. If
it's missing, the client writes without compression instead of aborting.
For archives that are mostly JPEGs, compression gains almost nothing; for
SQL dumps it gains a lot.

Local retention is independent of retention on the Manage server. On the
server it's maintained centrally in the server settings, usually
considerably higher than locally.

## Interplay with the project

If the project already defines a constant itself, that value wins, because
the client's `config.php` loads before the defaults, and every default is
set with `if (!defined(...))`. This lets a project configure its paths
centrally and have the client pick them up.

## Next

- [04_FUNCTION_API](04_FUNCTION_API.md) – the callable functions
- [09_TROUBLESHOOTING](09_TROUBLESHOOTING.md) – error messages and their causes