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
+37 -52
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 |
| `code` | Browser-based VS Code IDE with Anthropic API access | code |
## Tools
## Config files
| File | Description |
|---|---|
| `stacks.sh` | CLI to manage stacks, services, scaffolding, updates, and backups |
| `.env` | Root config: `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` (gitignored) |
| `.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.
```bash
./stacks.sh help
```
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.
**Stack commands** — all accept one or more stack names or glob patterns (omit for all stacks):
```bash
./stacks.sh ls # list all stacks with live container status
./stacks.sh ps gitea # container status table
./stacks.sh up # start all stacks
./stacks.sh up gitea traefik # start specific stacks
./stacks.sh down 'g*' # stop stacks matching glob
./stacks.sh restart 'g*,traefik' # glob + exact name, comma-separated
./stacks.sh pull --parallel # pull all images in parallel
./stacks.sh logs -f gitea # follow logs
./stacks.sh logs -n 100 gitea n8n # tail multiple stacks
./stacks.sh exec gitea gitea gitea admin user list # exec in container
./stacks.sh run passbolt passbolt bin/cake passbolt healthcheck
stacks ls # list all stacks with live container status
stacks ps gitea # container status table
stacks up # start all stacks
stacks up gitea traefik # start specific stacks
stacks down 'g*' # stop stacks matching glob
stacks restart 'g*,traefik' # glob + exact name, comma-separated
stacks pull --parallel # pull all images in parallel
stacks logs -f gitea # follow logs
stacks logs -n 100 gitea n8n # tail multiple stacks
stacks exec gitea gitea gitea admin user list # exec in container
stacks run passbolt passbolt bin/cake passbolt healthcheck
```
**Service management** (reads `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` from root `.env`):
```bash
./stacks.sh update install # write & enable systemd update timer
./stacks.sh update run # run update now
./stacks.sh update status # show timer/service status
./stacks.sh update logs # show journal logs
stacks update install # write & enable systemd update timer
stacks update run # run update now
stacks update status # show timer/service status
stacks update logs # show journal logs
./stacks.sh backup install # write & enable systemd backup timer
./stacks.sh backup run # run backup now (auto-detects <stack>_db containers)
./stacks.sh backup snapshots # list restic snapshots
stacks backup install # write & enable systemd backup timer
stacks backup run # run backup now (auto-detects <stack>_db containers)
stacks backup snapshots # list restic snapshots
```
**Scaffold a new stack:**
```bash
./stacks.sh new myapp # basic stack with Traefik labels
./stacks.sh new myapp --db postgres # with Postgres service
./stacks.sh new myapp --db postgres --redis # with Postgres + Redis
./stacks.sh new myapp --no-traefik # expose port instead of Traefik
stacks new myapp # basic stack with Traefik labels
stacks new myapp --db postgres # with Postgres service
stacks new myapp --db postgres --redis # with Postgres + Redis
stacks new myapp --no-traefik # expose port instead of Traefik
```
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`
## Deployment
@@ -96,7 +81,7 @@ cp <stack>/.env.example <stack>/.env
rsync -avz <stack>/ vps:~/stacks/<stack>/
# Start a stack
ssh vps 'cd ~/stacks/<stack> && docker compose up -d'
ssh vps 'stacks up <stack>'
```
## Network
@@ -109,14 +94,14 @@ Runs daily at 3:00 AM via a systemd timer. Detects Postgres databases automatica
```bash
# First-time setup on VPS
cp .env.example .env && $EDITOR .env # set RESTIC_REPOSITORY, RESTIC_PASSWORD, WEBHOOK_URL
source .env && restic init # initialise restic repo
cp .env.example .env && $EDITOR .env # set RESTIC_REPOSITORY, RESTIC_PASSWORD, WEBHOOK_URL
source .env && restic init # initialise restic repo
./stacks.sh backup install # write & enable systemd unit + timer
./stacks.sh backup run # test run
./stacks.sh backup snapshots # list snapshots
./stacks.sh backup status # timer/service status
./stacks.sh backup logs # journald logs
stacks backup install # write & enable systemd unit + timer
stacks backup run # test run
stacks backup snapshots # list snapshots
stacks backup status # timer/service status
stacks backup logs # journald logs
```
## 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.
```bash
./stacks.sh update install # write & enable systemd unit + timer
./stacks.sh update run # test run
./stacks.sh update status # timer/service status
./stacks.sh update logs # journald logs
stacks update install # write & enable systemd unit + timer
stacks update run # test run
stacks update status # timer/service status
stacks update logs # journald logs
```
## Notifications