131 lines
4.8 KiB
Markdown
131 lines
4.8 KiB
Markdown
# services
|
|
|
|
One folder per service. Each folder must contain a `metadata.json` describing the service
|
|
(including the Docker Compose definition used to deploy it). The folder may also contain any extra
|
|
files the service needs — a `Caddyfile`, a `Dockerfile`, static assets — which the installer copies
|
|
into the deploy directory.
|
|
|
|
## Folder conventions
|
|
|
|
- The folder name **must** equal the service `id` in `metadata.json` (lowercase kebab-case).
|
|
- Only folders that contain a valid `metadata.json` are treated as services by the installer.
|
|
- After adding, editing, or removing a service, regenerate the index:
|
|
|
|
```bash
|
|
cd installer
|
|
bun run catalog
|
|
```
|
|
|
|
This rewrites [`catalog.json`](catalog.json), which the installer uses as a one-request listing.
|
|
|
|
## Extra files
|
|
|
|
A service folder can contain files beyond `metadata.json` — for example the `allprox` service ships
|
|
a `Caddyfile` and a `portal/index.html`. On install/update the installer copies the whole folder
|
|
(except `metadata.json`) into `~/.homelab/services/<id>/`, preserving subdirectories.
|
|
|
|
Reference those files from `compose.volumes` with **relative** paths:
|
|
|
|
```json
|
|
"volumes": [
|
|
"./Caddyfile:/etc/caddy/Caddyfile:ro",
|
|
"./portal:/srv/portal:ro"
|
|
]
|
|
```
|
|
|
|
Because the generated `docker-compose.yml` lives in the same directory, `docker compose` resolves
|
|
the `./...` paths against it.
|
|
|
|
## Shared networks
|
|
|
|
Services that need to talk to each other (e.g. `allprox` → `authelia` → `lldap`) join an external
|
|
Docker network. Declare it at the top level of `metadata.json` and attach the service to it:
|
|
|
|
```json
|
|
"networks": { "homelab": { "external": true } },
|
|
"compose": {
|
|
"networks": ["homelab"]
|
|
}
|
|
```
|
|
|
|
The installer creates the external network automatically (if it doesn't already exist) before
|
|
running `docker compose up`.
|
|
|
|
## `metadata.json` reference
|
|
|
|
| Field | Required | Type | Description |
|
|
| --- | --- | --- | --- |
|
|
| `id` | ✅ | string | Unique kebab-case id, equal to the folder name. |
|
|
| `name` | ✅ | string | Human-readable name shown in the TUI. |
|
|
| `description` | ✅ | string | Short description. |
|
|
| `version` | ✅ | string | Version string for change detection on update. |
|
|
| `compose` | ✅ | object | A Docker Compose **service** definition (`image`, `ports`, `volumes`, `environment`, …). The installer wraps it in a generated `docker-compose.yml`. |
|
|
| `volumes` | — | object | Optional top-level named volumes to declare. |
|
|
| `networks` | — | object | Optional top-level networks to declare. |
|
|
| `env` | — | array | Variables the installer resolves for you (see below). |
|
|
| `category` | — | string | Grouping shown as a hint in the TUI. |
|
|
| `tags` | — | string[] | Free-form tags. |
|
|
| `icon` | — | string | URL to an icon. |
|
|
| `author` | — | string | Upstream author. |
|
|
| `license` | — | string | License of the deployed software. |
|
|
| `homepage` | — | string | Project homepage URL. |
|
|
| `documentation` | — | string | Documentation URL. |
|
|
| `dependsOn` | — | string[] | Ids of services that should be installed first (informational). |
|
|
| `notes` | — | string | Free-form notes shown by `info`. |
|
|
|
|
A machine-readable JSON Schema is available at [`docs/metadata-schema.json`](../docs/metadata-schema.json).
|
|
|
|
### `compose` (the service definition)
|
|
|
|
This object is the value you would normally put under a service key in `docker-compose.yml`. For
|
|
example:
|
|
|
|
```json
|
|
{
|
|
"image": "ghcr.io/example/myapp:1.0.0",
|
|
"container_name": "myapp",
|
|
"restart": "unless-stopped",
|
|
"ports": ["8080:8080"],
|
|
"volumes": ["myapp_data:/data"],
|
|
"environment": ["TZ=${TZ}"]
|
|
}
|
|
```
|
|
|
|
The installer turns it into:
|
|
|
|
```yaml
|
|
services:
|
|
myapp:
|
|
image: ghcr.io/example/myapp:1.0.0
|
|
# ...
|
|
```
|
|
|
|
Pin images to a tag so updates are predictable; the installer compares `version` to decide whether
|
|
an update is available.
|
|
|
|
### `env` (interactive variables)
|
|
|
|
Each entry describes a variable the installer should collect (and write to `.env`):
|
|
|
|
```json
|
|
{
|
|
"name": "WEBPASSWORD",
|
|
"label": "Web admin password",
|
|
"description": "Password for the web UI",
|
|
"default": "change-me",
|
|
"required": true,
|
|
"secret": true,
|
|
"options": []
|
|
}
|
|
```
|
|
|
|
- `name` (required) — the variable name. Reference it in `compose` as `${NAME}`.
|
|
- `label` / `description` — shown when prompting.
|
|
- `default` — used when the user accepts the default or runs non-interactively.
|
|
- `required` — a missing value is an error in non-interactive mode unless a `default` is set.
|
|
- `secret` — mask input at the prompt (e.g. passwords).
|
|
- `options` — if provided, the installer offers a fixed choice list instead of free text.
|
|
- `generate` — generate a random 64-char hex secret instead of prompting (for JWT/session secrets).
|
|
|
|
Docker Compose automatically reads the `.env` written next to the generated compose file, so
|
|
`${NAME}` references resolve at `docker compose up` time.
|