manager/docs/INSTANCE_MANAGEMENT.md

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:

./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 – installation
• RELEASING – publishing releases
• ../client-package/docs/08_PROTOCOL.md – authentication in detail