Your Name
138 lines
4.8 KiB
Markdown
138 lines
4.8 KiB
Markdown
# How-To: `pos docker`
|
|
|
|
Manage self-hosted services, watch containers, and spin up disposable VMs.
|
|
Tools: `compose`, `ps`, `health`, `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 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 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)
|