we do not (ab)use cookies!
if you use a free browser, follow our free and secure web version of this site below, to remove this reminder:
ahoxus.org/forge/pipeline
# pipeline
ahoxus operational flow — how changes reach production without breaking things.
## principles
1. **bat-first** — backup, test, apply. never apply directly without a test path.
2. **immutable releases** — every deploy is a new directory. previous release stays as rollback.
3. **verify before activate** — published commit on remote forge ≠ live. verify first, then activate.
4. **merge, never force push** — public history is sacred. revert if needed.
## stages
```
idea → stage → proof → commit → push → verify → activate
↑___________| | |
rollback here | |
↓ |
published commit |
↓
live
```
### stage
prepare the change in a clean working tree.
- edit source files in `/root/ahoxus.org/`
- for spirits: edit worktree (not release dir)
- check: `git diff` shows only intended changes
### proof
test before commit. the proof stage catches errors before they enter history.
| check | command | what it catches |
|-------|---------|----------------|
| syntax | eyeball or html validator | broken html |
| links | `grep -o 'href="http://ahoxus.org/[^"]*"' file.html` | stale paths |
| spirit path | `realpath /root/spirit/plugins/asuxoi/handler.py` | editing release instead of worktree |
| render | open in browser or `w3m -dump` | visual breakage |
| mobile | narrow browser window | layout issues |
**today's bug that proof would have caught:**
> edited `/root/cauenix/releases/.../commands.py` but cauenix loads from `/root/cauenix/worktrees/.../plugins/asuxoi/commands.py`. the search command was deployed to a dead path.
**proof check:** `ps aux | grep cauenix` → check which python loads which path → verify edit target.
### commit
once proof passes, commit with a descriptive message.
```bash
cd /root/ahoxus.org
git add -A
git diff --cached --stat # verify what's going in
git commit -m "component: what changed"
```
### push
push to remote forge(s). for ahoxus.org this means codeberg.
```bash
git push origin main
```
**wait for CI if configured** (none yet for ahoxus.org static).
### verify
verify the published commit before activating.
| check | how |
|-------|-----|
| commit on remote | `git ls-remote origin main` |
| diff matches local | `git diff main..origin/main` (should be empty) |
| files present | browse codeberg commit tree |
| tag immutable | `git tag -a deploy-$(date -u +%Y%m%dT%H%MZ) origin/main` |
### activate
sync to live webroot only after verify passes.
```bash
# immutable release pattern
cp -r /root/ahoxus.org/.deployed /var/www/ahoxus.org
# or for single files:
cp /root/ahoxus.org/page.html /var/www/ahoxus.org/page.html
```
**rollback:** the previous release directory or previous file version stays until overwritten. for git-tracked files, any previous commit is a rollback point.
## toolbox pattern
instead of global state, pass a toolbox/context object.
```python
# bad — global
deploy_target = "/var/www/ahoxus.org"
def deploy():
shutil.copy("page.html", deploy_target)
# good — toolbox
def deploy(toolbox):
shutil.copy("page.html", toolbox["webroot"])
toolbox = {
"webroot": "/var/www/ahoxus.org",
"gitroot": "/root/ahoxus.org",
"verify": True,
}
deploy(toolbox)
```
this makes test/production switches explicit and prevents "it worked on my machine" bugs.
## bats (behavioral acceptance tests)
automated checks that prove a deploy worked.
| test | command | passes when |
|------|---------|-------------|
| page loads | `curl -s -o /dev/null -w "%{http_code}" http://ahoxus.org/` | `200` |
| css loads | `curl -s http://ahoxus.org/nav.css | head -1` | not empty |
| ahotml parses | `curl -s http://ahoxus.org/ahotml/ | grep -o ''` | found |
| signature present | `curl -s http://ahoxus.org/ | grep 'secure-warning'` | found |
| menu sticky | visual check: scroll down, hamburger visible | always visible |
run bats after every activate. if a bat fails, rollback immediately.
## rollback
```bash
# git rollback: revert the bad commit
git revert HEAD --no-edit
git push origin main
# file rollback: copy from previous release
cp /var/www/ahoxus.org/.previous/page.html /var/www/ahoxus.org/page.html
# full rollback: restore from git archive
git archive HEAD~1 | tar -x -C /var/www/ahoxus.org/
```
## emergency sleep
if a deploy breaks production and you cannot rollback quickly:
```bash
# luianix/hohoxus: put system in emergency sleep
echo '{"mode":"sleep"}' > /root/luianix/luianix-control.json
# this stops the gateway from responding until fixed
```
with love, fupl