# Managing Instances

## Overview

An instance is one installation of the served product — for example
"Production", "Test", or a specific customer's installation. Every instance
has an id and a secret token.

Everything related lives under **Instances** in the UI.

## Creating an instance

1. Open **Instances**, enter an id, optionally a label and a note.
2. Create. Right after that the token is shown — **once**, together with a
   ready-made configuration block to copy.
3. Paste the block into the instance's `manage-client/config.php`.

Ids may contain letters, digits, dot, underscore and hyphen, must start with
a letter or a digit, and can be at most 120 characters long. They appear in
the backup file path; descriptive names such as `example-prod` and
`example-test` pay off.

## The token

- 32 random bytes, represented as 64 hex characters.
- The server stores only the SHA-256 hash. There is no way to display a
  token again later.
- If it's lost, a new one is generated — the old one becomes invalid
  immediately.

The token lets an instance download releases and upload backups. It
**cannot** download backups or change releases; both require logging into
the UI.

### Rotating the token

**Instances → Rotate token**. The old token loses its validity immediately;
the instance then reports `Authentifizierung fehlgeschlagen` ("authentication
failed" — the literal, still German, text the API returns) until the new
token is entered. Plan for short outages of cron jobs accordingly.

Reasons to rotate: suspected compromise, staff changes, handing over a
project.

## Deactivate instead of delete

**Deactivate** leaves the instance in place but rejects every API request
with `403`. The right move when an installation is temporarily shut down or
something is unclear — the token stays valid and the instance is back in
service with one click.

**Remove** deletes the registry entry. The stored backups remain and stay
visible and downloadable under **Backups**; there they are marked as "no
longer registered". New uploads are no longer possible.

## Status display

The overview shows, for each instance:

| Field | Source |
|---|---|
| Status | `active`, `inactive` (not seen for more than 7 days) or `deactivated` |
| Version | the instance's latest report |
| Update | comparison of this version against the current release |
| Last seen | every authenticated request updates this value |
| Last backup | timestamp of the last received backup |
| Pending migrations | from the instance's heartbeat |

`inactive` on a running installation usually means the heartbeat cron job
isn't running. Without cron, an instance only checks in when someone uses
the UI in the project.

Pending migrations are the most important warning sign: they mean an update
was rolled out, but part of the post-update step failed.

## Handing over the client package

The `client-package/` folder contains the client **and** its complete
documentation. To hand it over:

```bash
./scripts/build-client-package.sh --server-url https://manage.example.org
```

The result lands under `build/manage-client-<date>.zip`. With
`--server-url`, the server address is already filled into the bundled
`config.sample.php`; the receiving side only has to add the id and token.

The script removes every `config.php` and all log files before packing, so
no token from a test installation is shipped along.

## Multiple environments

Common setup for a product with a test and a production system:

| Instance | Purpose |
|---|---|
| `product-test` | gets new releases first |
| `product-prod` | follows after a successful test |

Both fetch the same `latest`. To keep a release on the test system only,
publish it and temporarily set the older one back as current — or roll it
out on the test system deliberately with `update --force`. Separate
channels per instance are deliberately absent; a second Manage server is
deployed for that.

## Next

- [SERVER_SETUP](SERVER_SETUP.md) – installation
- [RELEASING](RELEASING.md) – publishing releases
- [../client-package/docs/08_PROTOCOL.md](../client-package/docs/08_PROTOCOL.md) – authentication in detail