Add prefix/suffix support, short ID fallback, unit docs
- config: add Prefix/Suffix fields to Config struct - systemd: ServiceName/Generate/UnitPath/Install/Uninstall/Enable/Disable/Status all accept prefix+suffix - runtime: fall back to short container ID (12 chars) when container has no name - cmd: active, status, install all thread prefix/suffix from config - systemd/generator_test.go: updated all calls + added TestGenerate_WithPrefixSuffix - docs/generated-units.md: full examples of every unit type + ordering + naming - README: updated config docs, prefix/suffix section, link to docs/
This commit is contained in:
288
docs/generated-units.md
Normal file
288
docs/generated-units.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# Generated Systemd Unit Files
|
||||
|
||||
Unitdore generates `.service` files from your `units.yaml` config.
|
||||
This document shows every combination with annotated examples.
|
||||
|
||||
---
|
||||
|
||||
## System Unit (root, no user)
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
units:
|
||||
- name: nginx
|
||||
runtime: podman
|
||||
order: 1
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Written to:** `/etc/systemd/system/unitdore-nginx.service`
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/unitdore-nginx.service
|
||||
# Generated by unitdore — do not edit manually
|
||||
|
||||
[Unit]
|
||||
Description=Unitdore: nginx (podman)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/podman start -a nginx
|
||||
ExecStop=/usr/bin/podman stop nginx
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- `After=network.target` ensures the network is up before starting
|
||||
- `WantedBy=multi-user.target` means it starts in normal boot runlevel
|
||||
- `Restart=on-failure` restarts the container if it exits unexpectedly
|
||||
|
||||
---
|
||||
|
||||
## System Unit (Docker)
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
units:
|
||||
- name: redis
|
||||
runtime: docker
|
||||
order: 1
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Written to:** `/etc/systemd/system/unitdore-redis.service`
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/unitdore-redis.service
|
||||
# Generated by unitdore — do not edit manually
|
||||
|
||||
[Unit]
|
||||
Description=Unitdore: redis (docker)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/docker start redis
|
||||
ExecStop=/usr/bin/docker stop redis
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Docker uses `docker start <name>` (no `-a` flag needed)
|
||||
|
||||
---
|
||||
|
||||
## User Unit (rootless container)
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
units:
|
||||
- name: myapp
|
||||
runtime: podman
|
||||
user: hein
|
||||
order: 2
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Written to:** `/home/hein/.config/systemd/user/unitdore-myapp.service`
|
||||
|
||||
```ini
|
||||
# ~/.config/systemd/user/unitdore-myapp.service
|
||||
# Generated by unitdore — do not edit manually
|
||||
|
||||
[Unit]
|
||||
Description=Unitdore: myapp (podman)
|
||||
After=default.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/podman start -a myapp
|
||||
ExecStop=/usr/bin/podman stop myapp
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- User units use `After=default.target` and `WantedBy=default.target`
|
||||
- The file is written to the user's own systemd directory
|
||||
- Unitdore calls `runuser -u hein -- systemctl --user` for enable/start/status
|
||||
|
||||
---
|
||||
|
||||
## Custom Command
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
units:
|
||||
- name: myscript
|
||||
runtime: podman
|
||||
command: /opt/myapp/start.sh
|
||||
order: 3
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Written to:** `/etc/systemd/system/unitdore-myscript.service`
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/unitdore-myscript.service
|
||||
# Generated by unitdore — do not edit manually
|
||||
|
||||
[Unit]
|
||||
Description=Unitdore: myscript (podman)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/opt/myapp/start.sh
|
||||
ExecStop=
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- When `command` is set, it is used verbatim as `ExecStart`
|
||||
- `ExecStop` is left empty — systemd will send SIGTERM to the process group
|
||||
|
||||
---
|
||||
|
||||
## With Prefix and Suffix
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
prefix: prod-
|
||||
suffix: -svc
|
||||
|
||||
units:
|
||||
- name: nginx
|
||||
runtime: podman
|
||||
order: 1
|
||||
enabled: true
|
||||
- name: api
|
||||
runtime: docker
|
||||
order: 2
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Written to:**
|
||||
- `/etc/systemd/system/unitdore-prod-nginx-svc.service`
|
||||
- `/etc/systemd/system/unitdore-prod-api-svc.service`
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/unitdore-prod-nginx-svc.service
|
||||
# Generated by unitdore — do not edit manually
|
||||
|
||||
[Unit]
|
||||
Description=Unitdore: nginx (podman)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/podman start -a nginx
|
||||
ExecStop=/usr/bin/podman stop nginx
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- `prefix` and `suffix` apply to the **service file name only** — the container name stays unchanged
|
||||
- Useful for distinguishing environments (`prod-`, `staging-`) or roles (`-web`, `-worker`)
|
||||
|
||||
---
|
||||
|
||||
## Container Named by Short ID
|
||||
|
||||
If a container has no name (e.g. started with `docker run` without `--name`), unitdore uses its short container ID (first 12 characters) as the unit name.
|
||||
|
||||
**Example:** Container ID `a3f2c1b9e4d7` with no name →
|
||||
|
||||
**Config entry added by `syncup`:**
|
||||
```yaml
|
||||
units:
|
||||
- name: a3f2c1b9e4d7
|
||||
runtime: docker
|
||||
order: 1
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Written to:** `/etc/systemd/system/unitdore-a3f2c1b9e4d7.service`
|
||||
|
||||
**Tip:** After `syncup`, use `unitdore edit` to give it a proper name before running `install`.
|
||||
|
||||
---
|
||||
|
||||
## Startup Ordering Example
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
units:
|
||||
- name: postgres
|
||||
runtime: podman
|
||||
order: 1
|
||||
enabled: true
|
||||
|
||||
- name: redis
|
||||
runtime: podman
|
||||
order: 1 # same order = starts in parallel
|
||||
enabled: true
|
||||
|
||||
- name: api
|
||||
runtime: podman
|
||||
order: 2 # waits until order 1 group is started
|
||||
enabled: true
|
||||
|
||||
- name: nginx
|
||||
runtime: podman
|
||||
order: 3
|
||||
enabled: true
|
||||
```
|
||||
|
||||
`unitdore active` starts units in ascending `order` value, lowest first.
|
||||
Units with the **same order** are started together (parallel).
|
||||
|
||||
---
|
||||
|
||||
## Disabled Unit
|
||||
|
||||
**Config:**
|
||||
```yaml
|
||||
units:
|
||||
- name: oldthing
|
||||
runtime: podman
|
||||
order: 1
|
||||
enabled: false
|
||||
disabled_reason: container not found
|
||||
```
|
||||
|
||||
- `unitdore install` will **remove** the `.service` file if it exists
|
||||
- `unitdore active` will **skip** disabled units
|
||||
- `unitdore status` shows the reason in the REASON column
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Service File Locations
|
||||
|
||||
| Scenario | Path |
|
||||
|---|---|
|
||||
| System unit (root) | `/etc/systemd/system/unitdore-<name>.service` |
|
||||
| User unit | `/home/<user>/.config/systemd/user/unitdore-<name>.service` |
|
||||
| With prefix `prod-` | `/etc/systemd/system/unitdore-prod-<name>.service` |
|
||||
| With suffix `-svc` | `/etc/systemd/system/unitdore-<name>-svc.service` |
|
||||
| With both | `/etc/systemd/system/unitdore-prod-<name>-svc.service` |
|
||||
Reference in New Issue
Block a user