Operations
Phelix in Docker
Agent identity rules and persistent data for containerized Phelix installations.
When Phelix itself runs in Docker, each Phelix container is an independent agent. Its identity belongs to the Phelix runtime, not to the physical or VM host and not to the application it manages. This lets several Phelix containers on one host report to the same backend without colliding.
The identity rule
machine_id ≠ agent_id ≠ app_id ≠ instance_id| Identifier | What it identifies |
|---|---|
| machine_id | A physical or virtual host. Phelix does not use it as its agent identity. |
| agent_id | One persistent Phelix installation/runtime. |
| app_id | An application, independently of its agent. |
| instance_id | A particular deployed or running instance. |
Persistent agent data
Phelix creates /var/lib/phelix/agent-id on first start and reuses the UUID on every later start. Its application registry (apps.json) lives in the same directory, so application IDs persist too. Mount a different persistent volume for every Phelix container. Do not mount /etc/machine-id into the containers, and never share one /var/lib/phelix volume between them.
services: billing: image: <your-phelix-image> command: ["phelix", "monitor"] hostname: billing-agent volumes: - phelix-billing-data:/var/lib/phelix auth: image: <your-phelix-image> command: ["phelix", "monitor"] hostname: auth-agent volumes: - phelix-auth-data:/var/lib/phelix user: image: <your-phelix-image> command: ["phelix", "monitor"] hostname: user-agent volumes: - phelix-user-data:/var/lib/phelix admin: image: <your-phelix-image> command: ["phelix", "monitor"] hostname: admin-agent volumes: - phelix-admin-data:/var/lib/phelix volumes: phelix-billing-data: phelix-auth-data: phelix-user-data: phelix-admin-data:docker compose up -ddocker compose logs -f billing| Operation | Result |
|---|---|
| docker restart billing | Same agent_id, therefore the same backend server/agent record. |
| Remove and recreate with the phelix-billing-data volume | Same agent_id, therefore the same backend server/agent record. |
| Recreate without the Phelix data volume | A new agent_id and a new backend server/agent record. |
The backend registers an agent idempotently: an existing agent_id updates its record and last-seen data; a new one creates a record. A reconnect must never create another server merely because the container restarted.
Application identity
phelix build billing (and equivalent application-creation flows) generates an app_id once and persists it in /var/lib/phelix/apps.json. The application may be related to an agent/server, but its ID must not be derived from server_id, agent_id, or its name. The backend may enforce unique names within an agent using UNIQUE(server_id, name); names are not globally unique.