warkanum
f0827fcdd7
- syncup: podman first, docker only as fallback (podman wins on name clash;
existing docker units found in podman switch to podman)
- syncup: group podman-compose containers into one `kind: stack` unit per
project (project, working_dir, compose_files, compose_bin from labels);
disable existing member units ("part of stack <project>")
- generator: compose mode (podman-compose up/stop, WorkingDirectory) with
pod start/stop fallback when compose binary/dir/files are missing
- reconcile: stacks disabled with "stack not found" when neither compose
files nor pod exist
- root: scan root + rootless users listed in `users:` (podman only)
- non-root: config ~/.config/unitdore/units.yaml, own user units only
- sysuser package: runuser with XDG_RUNTIME_DIR/DBUS env, home/linger lookup
- install: warn when linger is not enabled for user units
- testdata/stack: podman-compose test stack and captured podman ps fixture
- docs: README, generated-units, man page, AGENTS, PLAN
105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
## Project Overview
|
|
|
|
**Unitdore** is a Go CLI tool that bridges container runtimes (Podman, Docker) and systemd. It discovers running containers, stores them in a YAML config, and generates + manages systemd `.service` unit files for each one.
|
|
|
|
# Agent Rules
|
|
|
|
Keep answers short. Question everything, never assume or guess. Ask if unsure.
|
|
You must use the AMCS MCP system tools. Set **unitdore** as the active project and always capture summaries of what was done as thoughts using the `capture_thought` tool. If AMCS is not available, write files to `docs/llm/log/yyyymmdd_hh.md`.
|
|
|
|
# Tools to use
|
|
|
|
When writing Go: `doc/tools/go-skill.md` (if present), otherwise follow standard Go conventions.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
make build # Compile binary: ./unitdore
|
|
make install # Install binary to /usr/bin, man page, create /etc/unitdore
|
|
make uninstall # Remove binary and man page
|
|
make test # go test ./... -v
|
|
make test-short # go test ./...
|
|
make lint # go vet ./...
|
|
make clean # Remove built binary
|
|
make release-version # Bump patch version, commit, tag, and push
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
cmd/ # Cobra commands (edit, install, list, root, start, startall,
|
|
# status, stop, stopall, syncup, uninstall, update)
|
|
config/ # Config struct + YAML load/save (units.yaml)
|
|
runtime/ # Docker and Podman runtime abstraction, compose labels
|
|
sysuser/ # run commands as root/user (runuser), home/linger lookup
|
|
testdata/stack # podman-compose test stack + captured `podman ps` fixture
|
|
systemd/ # .service file generator and systemd manager
|
|
docs/ # generated-units.md (unit file examples), unitdore.1 (man page)
|
|
```
|
|
|
|
### Key packages
|
|
|
|
- **`config`** — `Unit` and `Config` structs; `Load`, `Save`, `FindUnit`, `AddUnit`
|
|
- **`runtime`** — `ContainerRuntime` interface; `docker.go`, `podman.go` implementations
|
|
- **`systemd`** — `generator.go` builds `.service` file content; `manager.go` calls `systemctl`
|
|
|
|
### Config file
|
|
|
|
**Location:** `/etc/unitdore/units.yaml`
|
|
|
|
```yaml
|
|
prefix: "" # prepended to service file name (e.g. "prod-")
|
|
suffix: "" # appended to service file name (e.g. "-svc")
|
|
users: [] # root only: rootless users scanned by syncup
|
|
|
|
units:
|
|
- name: nginx
|
|
runtime: podman # podman | docker
|
|
user: "" # empty = system unit; set for rootless user unit
|
|
command: "" # override ExecStart entirely
|
|
order: 1 # startup order, lower = earlier; same = parallel
|
|
delay: 0s # delay after previous order group
|
|
enabled: true
|
|
disabled_reason: "" # auto-set by syncup reconciliation
|
|
restart: false # Restart=on-failure
|
|
restart_sec: 0 # RestartSec
|
|
restart_retries: 0 # StartLimitBurst
|
|
kind: container # container | stack (podman-compose project)
|
|
project: "" # stack: compose project
|
|
working_dir: "" # stack: compose dir (from labels)
|
|
compose_files: [] # stack: relative to working_dir
|
|
compose_bin: "" # stack: podman-compose path
|
|
```
|
|
|
|
Non-root runs use `~/.config/unitdore/units.yaml` and manage only own user units.
|
|
|
|
### Generated 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` |
|
|
|
|
### Libraries
|
|
|
|
- `github.com/spf13/cobra` — CLI framework
|
|
- `gopkg.in/yaml.v3` — config parsing
|
|
|
|
## Testing
|
|
|
|
Tests exist in:
|
|
- `config/config_test.go`
|
|
- `runtime/runtime_test.go`
|
|
- `cmd/syncup_test.go`
|
|
- `sysuser/sysuser_test.go`
|
|
- `systemd/generator_test.go`
|
|
|
|
Always run `make test` before marking a task complete. Add tests for new behaviour in the same package as the code under test.
|
|
|
|
## Additional documentation
|
|
|
|
- `docs/generated-units.md` — full annotated examples of every generated unit file combination
|
|
- `docs/unitdore.1` — man page
|