unitdore/docs/generated-units.md

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:

units:
  - name: nginx
    runtime: podman
    order: 1
    enabled: true

Written to: /etc/systemd/system/unitdore-nginx.service

# /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:

units:
  - name: redis
    runtime: docker
    order: 1
    enabled: true

Written to: /etc/systemd/system/unitdore-redis.service

# /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:

units:
  - name: myapp
    runtime: podman
    user: hein
    order: 2
    enabled: true

Written to: /home/hein/.config/systemd/user/unitdore-myapp.service

# ~/.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:

units:
  - name: myscript
    runtime: podman
    command: /opt/myapp/start.sh
    order: 3
    enabled: true

Written to: /etc/systemd/system/unitdore-myscript.service

# /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:

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

# /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:

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:

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:

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