Linux_post_install/DOC/howto/docker.md

# How-To: `pos docker`

Manage self-hosted services, watch containers, and spin up disposable VMs.
Tools: `compose`, `ps`, `health`, `stack`, `vbox`.

| Tool | What it does |
|------|--------------|
| `pos docker compose` | ScaleTail service manager (deploy/stop/logs/update) |
| `pos docker ps` | Enhanced container overview (health, IPs, ports, uptime) |
| `pos docker health` | One-glance health dashboard (exits 1 if unhealthy) |
| `pos docker stack` | Containers grouped by compose stack (`-a` includes stopped) |
| `pos docker vbox` | Disposable Docker containers as lightweight VMs |

---

## `pos docker compose` — self-hosted services (ScaleTail)

Deploy 119+ self-hosted service templates (Jellyfin, Home Assistant, …) on
Tailscale. Template set lives in
`/usr/local/share/linux_post_install/scale-tail/services/`.

```bash
pos docker compose ls                      # list available templates
pos docker compose installed               # what's deployed locally
pos docker compose up jellyfin             # deploy or start
pos docker compose down actual-budget      # stop + remove
pos docker compose restart home-assistant
pos docker compose logs jellyfin -f        # follow logs
pos docker compose update                  # pull latest templates + refresh deployments
pos docker compose config                  # show global config
pos docker compose config set TS_AUTHKEY=tskey-auth-xxxxx
pos docker compose config set TZ=Asia/Tokyo
pos docker compose config set SERVICES_BASE=/data
pos docker compose config edit             # open global config in $EDITOR
```

### Config strategy (three layers, each overrides the one above)

1. **Template defaults** — `…/services/<name>/.env`
2. **Global config** — `~/.config/linux_post_install/compose.env`
   keys: `TS_AUTHKEY` | `TZ` | `DNS_SERVER` | `SERVICES_BASE`
3. **Per-service config** — `/srv/<service>/.env` (or `$SERVICES_BASE/<service>/.env`)

On first `up`, the per-service `.env` is generated from the template + your
global config, and is **never overwritten** afterwards (not even by `update`).

### Quick start

```bash
pos docker compose config set TS_AUTHKEY=tskey-auth-xxxxx   # required
pos docker compose up jellyfin
# open https://jellyfin.tail-xxxxx.ts.net
```

**Recipes:**
- Change timezone once, applies everywhere: `pos docker compose config set TZ=Asia/Tokyo`
- Store deployments on a bigger disk: `pos docker compose config set SERVICES_BASE=/data`
- Tweak one service's options after deploy: edit `/srv/<service>/.env` directly
  (never clobbered).

**Troubleshooting:**
- `up` fails with auth errors → `TS_AUTHKEY` missing/expired; re-set it.
- Service reachable only on the host → Tailscale up/`tailscale up` not running;
  check `TS_AUTHKEY` in the service `.env`.
- `update` doesn't change your customizations → expected; per-service `.env` is
  preserved by design.

---

## `pos docker ps` — better `docker ps`

```bash
pos docker ps
```

Enhanced overview: health status, uptime, IPs, port mappings.

**Recipe:** pair with the daily digest — the health report summarizes
unhealthy/restarting containers; when it flags one, `pos docker ps` shows the
details (IPs/ports/uptime) to investigate.

---

## `pos docker health` — is everything healthy?

```bash
pos docker health
```

Prints health + uptime per container; **exits 1 if any container is unhealthy**
(useful for scripts/CI/monitoring).

**Recipe:** alert on failure in your own script:
```bash
pos docker health >/dev/null || notify_send "Docker unhealthy"
```

**Troubleshooting:** a container shows no health status if its image has no
`HEALTHCHECK` — that's fine, it counts as "no healthcheck configured" (exit 0),
not unhealthy.

---

## `pos docker stack` — containers by compose stack

```bash
pos docker stack          # running containers grouped by compose project
pos docker stack -a       # include stopped/exited containers
```

Grouped view of your compose deployments: every stack is a section with its
services (container name, status, ports); containers started outside compose
land in a `Standalone` group at the end. `-a` behaves like `docker ps -a` and
also shows exited services (e.g. one-shot migration jobs that `docker ps`
hides).

**Recipe:** after `pos docker compose up <svc>`, confirm it joined the right
stack:

```bash
pos docker stack | grep -A5 <svc>
```

**Recipe:** spot what's restarting across all stacks at a glance (yellow
`Restarting` / red `Exited` statuses stand out on a terminal).

---

## `pos docker vbox` — disposable VMs

Docker containers with a bind-mounted host dir so files persist even after the
container is removed. Great for labs, downloads, kali, throwaway services.

```bash
pos docker vbox create lab1                        # default dir ~/lab1
pos docker vbox create lab1 --dir .                # files land in cwd
pos docker vbox create lab1 --dir /mnt/data/lab1
pos docker vbox create kali kalilinux/kali-rolling # custom image
pos docker vbox enter lab1
pos docker vbox stop lab1
pos docker vbox start lab1
pos docker vbox rm lab1
pos docker vbox ls
```

**Recipe:** a disposable browsing/download box:
```bash
pos docker vbox create dl --dir /mnt/data/dl
pos docker vbox enter dl       # work inside; files persist in /mnt/data/dl
pos docker vbox rm dl          # container gone, files kept
```

**Troubleshooting:**
- `enter` needs a shell/SSH-capable image; `kalilinux/kali-rolling` works.
- If files "disappear" after `rm`, check you used `--dir` on a real path — the
  container image changes are lost, only the mounted dir persists.

---

## Related

- Reference + compose config strategy: [DOC/POS.md → docker](../POS.md)
- Container health in the daily digest: [system.md → health](system.md)