NextWks/AGENT.md

NextWorkspace — Agent Workflow Instructions

Versioning

• Format: MILESTONE.FEATURE.PATCH.BUILD (e.g., 0.1.0.0032)
• Bump VERSION file on every change before commit.
• Every commit must be tagged with the version: git tag v$(cat VERSION)

Deployment Model (Unified Script)

The project uses a single unified script at tools/nextwks.sh for all operations. The old deploy.sh and install.sh are deprecated.

Key principles:

• Source of truth is git remote only. No local /opt/NextWks repo.
• Building happens in /tmp/nextwks-build/ via git clone --depth 1 (fresh every time).
• Runtime goes to /opt/nextworkspace/ (configs, compose, binary, lng).
• Secrets persist in /opt/backup/.env and survive --destroy.
• Stack runs on a shared nextwks-net podman bridge network.

Script Flags

Flag	What it does
--install	First-time setup on a bare VM: installs deps, prompts for config, builds binary, generates configs, deploys stack
--update	Smart update: clones fresh, rebuilds binary, copies to target, bounces containers
--destroy	Full greenfield redeploy: tears down containers, wipes /opt/nextworkspace/, rebuilds from scratch using saved secrets from /opt/backup/.env

Workflow for Making Changes

1. Edit code in the development clone.
2. Test locally (e.g., go build && go run .).
3. Bump VERSION (increment BUILD).
4. Update CHANGELOG.md.
5. Commit: git add -A && git commit -m "description"
6. Tag: git tag v$(cat VERSION)
7. Push: git push origin main --tags
8. Deploy: sudo bash ~/nextwks.sh --update

Note: The deploy script is downloaded by users via curl from the repo. For production deployment, users run:

curl -sL https://git.lohmar.co.uk/lexton-it/NextWks/raw/branch/main/tools/nextwks.sh | sudo bash -s -- --install

Build Process

• Static Go binary: CGO_ENABLED=0 go build -o nextworkspace .
• Must run on Alpine in the container (no glibc dependency).
• Binary runs as PID 1 in the launcher container.

Architecture

Caddy (:80/:443, host ports)
  ├── auth.{DOMAIN} → Authelia :9091 (internal)
  ├── app.{DOMAIN}  → Launcher :9000 (internal) with forward auth
  └── www.{DOMAIN}  → static files

All three containers on nextwks-net (podman bridge).
Only Caddy exposes ports to host.

Config Template System

Config files use {PLACEHOLDER} syntax. The script substitutes values at deploy time:

File	Placeholders
config/caddy/Caddyfile	{DOMAIN}, {TLS_EMAIL}
config/authelia/configuration.yml	{DOMAIN}, {JWT_SECRET}, {SESSION_SECRET}, {SMTP_HOST}, {SMTP_PORT}, {SMTP_USER}, {SMTP_PASS}
config/authelia/users_database.yml	{ADMIN_PASSWORD_HASH}, {TLS_EMAIL}
compose/stack.yaml	{AUTHELIA_SECRET} (same as SESSION_SECRET)

Env Vault (/opt/backup/.env)

Persisted secrets across destroys:

DOMAIN=nextwks.eu
TLS_EMAIL=admin@nextwks.eu
ADMIN_USERNAME=master
ADMIN_PASSWORD=<generated>
SMTP_HOST=smtp.openxchange.eu
SMTP_PORT=587
SMTP_USER=post@nextwks.eu
SMTP_PASS=<prompted>
JWT_SECRET=<auto-generated>
SESSION_SECRET=<auto-generated>
ADMIN_PASSWORD_HASH=<bcrypt hash>

Health Check

After deploy, the script polls podman exec launcher wget -qO- http://127.0.0.1:9000/health up to 10 times (2s interval). Expected response: OK.

Commit Message Style

• Imperative mood ("Add", "Fix", "Update", "Bump")
• Reference the component if relevant ("launcher: add health endpoint")
• Keep under 72 chars for the first line