valknar/stacks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(stacks): update README — stacks.sh moved to scripts repo, use stacks alias

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
valknar
2026-06-20 15:53:16 +02:00
co-authored by Claude Sonnet 4.6
parent 056db5d6ea
commit 7ae681cc83
1 changed files with 37 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+35 -50
View File
@@ -18,72 +18,57 @@ Each stack is independently deployable with its own `compose.yml` and `.env`. Al
| `passbolt` | Password manager (GPG-encrypted, team sharing) | passbolt, db | | `passbolt` | Password manager (GPG-encrypted, team sharing) | passbolt, db |
| `code` | Browser-based VS Code IDE with Anthropic API access | code | | `code` | Browser-based VS Code IDE with Anthropic API access | code |
## Tools ## Config files
| File | Description | | File | Description |
|---|---| |---|---|
| `stacks.sh` | CLI to manage stacks, services, scaffolding, updates, and backups |
| `.env` | Root config: `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` (gitignored) | | `.env` | Root config: `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` (gitignored) |
| `.env.example` | Template for the root `.env` | | `.env.example` | Template for the root `.env` |
## stacks.sh ## Management
`stacks.sh` is the primary management CLI. It wraps `docker compose` with glob-based multi-stack targeting, manages the update and backup systemd services, scaffolds new stacks, and generates shell completions. Stacks are managed via `stacks.sh` from [git@dev.pivoine.art:valknar/scripts.git](ssh://git@dev.pivoine.art/valknar/scripts.git), available as `stacks` in PATH.
```bash
./stacks.sh help
```
**Stack commands** — all accept one or more stack names or glob patterns (omit for all stacks): **Stack commands** — all accept one or more stack names or glob patterns (omit for all stacks):
```bash ```bash
./stacks.sh ls # list all stacks with live container status stacks ls # list all stacks with live container status
./stacks.sh ps gitea # container status table stacks ps gitea # container status table
./stacks.sh up # start all stacks stacks up # start all stacks
./stacks.sh up gitea traefik # start specific stacks stacks up gitea traefik # start specific stacks
./stacks.sh down 'g*' # stop stacks matching glob stacks down 'g*' # stop stacks matching glob
./stacks.sh restart 'g*,traefik' # glob + exact name, comma-separated stacks restart 'g*,traefik' # glob + exact name, comma-separated
./stacks.sh pull --parallel # pull all images in parallel stacks pull --parallel # pull all images in parallel
./stacks.sh logs -f gitea # follow logs stacks logs -f gitea # follow logs
./stacks.sh logs -n 100 gitea n8n # tail multiple stacks stacks logs -n 100 gitea n8n # tail multiple stacks
./stacks.sh exec gitea gitea gitea admin user list # exec in container stacks exec gitea gitea gitea admin user list # exec in container
./stacks.sh run passbolt passbolt bin/cake passbolt healthcheck stacks run passbolt passbolt bin/cake passbolt healthcheck
``` ```
**Service management** (reads `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` from root `.env`): **Service management** (reads `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` from root `.env`):
```bash ```bash
./stacks.sh update install # write & enable systemd update timer stacks update install # write & enable systemd update timer
./stacks.sh update run # run update now stacks update run # run update now
./stacks.sh update status # show timer/service status stacks update status # show timer/service status
./stacks.sh update logs # show journal logs stacks update logs # show journal logs
./stacks.sh backup install # write & enable systemd backup timer stacks backup install # write & enable systemd backup timer
./stacks.sh backup run # run backup now (auto-detects <stack>_db containers) stacks backup run # run backup now (auto-detects <stack>_db containers)
./stacks.sh backup snapshots # list restic snapshots stacks backup snapshots # list restic snapshots
``` ```
**Scaffold a new stack:** **Scaffold a new stack:**
```bash ```bash
./stacks.sh new myapp # basic stack with Traefik labels stacks new myapp # basic stack with Traefik labels
./stacks.sh new myapp --db postgres # with Postgres service stacks new myapp --db postgres # with Postgres service
./stacks.sh new myapp --db postgres --redis # with Postgres + Redis stacks new myapp --db postgres --redis # with Postgres + Redis
./stacks.sh new myapp --no-traefik # expose port instead of Traefik stacks new myapp --no-traefik # expose port instead of Traefik
``` ```
Generates `compose.yml` (with healthchecks, `../.data/` volumes, Traefik labels) and `.env.example`. Generates `compose.yml` (with healthchecks, `../.data/` volumes, Traefik labels) and `.env.example`.
**Shell completion:**
```bash
# Dynamic — discovers stacks at tab-complete time (default)
./stacks.sh completion zsh --install
# Static — bakes current stack list in; useful on the VPS
./stacks.sh completion zsh --static --install
```
**Global flags:** `--dry-run`, `--parallel`, `--verbose`, `--quiet` **Global flags:** `--dry-run`, `--parallel`, `--verbose`, `--quiet`
## Deployment ## Deployment
@@ -96,7 +81,7 @@ cp <stack>/.env.example <stack>/.env
rsync -avz <stack>/ vps:~/stacks/<stack>/ rsync -avz <stack>/ vps:~/stacks/<stack>/
# Start a stack # Start a stack
ssh vps 'cd ~/stacks/<stack> && docker compose up -d' ssh vps 'stacks up <stack>'
``` ```
## Network ## Network
@@ -112,11 +97,11 @@ Runs daily at 3:00 AM via a systemd timer. Detects Postgres databases automatica
cp .env.example .env && $EDITOR .env # set RESTIC_REPOSITORY, RESTIC_PASSWORD, WEBHOOK_URL cp .env.example .env && $EDITOR .env # set RESTIC_REPOSITORY, RESTIC_PASSWORD, WEBHOOK_URL
source .env && restic init # initialise restic repo source .env && restic init # initialise restic repo
./stacks.sh backup install # write & enable systemd unit + timer stacks backup install # write & enable systemd unit + timer
./stacks.sh backup run # test run stacks backup run # test run
./stacks.sh backup snapshots # list snapshots stacks backup snapshots # list snapshots
./stacks.sh backup status # timer/service status stacks backup status # timer/service status
./stacks.sh backup logs # journald logs stacks backup logs # journald logs
``` ```
## Updates ## Updates
@@ -124,10 +109,10 @@ source .env && restic init # initialise restic repo
Runs nightly at 2:00 AM via a systemd timer. Pulls the latest image for every stack, recreates any container whose image changed, prunes dangling images, and sends a Telegram notification via n8n. Runs nightly at 2:00 AM via a systemd timer. Pulls the latest image for every stack, recreates any container whose image changed, prunes dangling images, and sends a Telegram notification via n8n.
```bash ```bash
./stacks.sh update install # write & enable systemd unit + timer stacks update install # write & enable systemd unit + timer
./stacks.sh update run # test run stacks update run # test run
./stacks.sh update status # timer/service status stacks update status # timer/service status
./stacks.sh update logs # journald logs stacks update logs # journald logs
``` ```
## Notifications ## Notifications