MARKDOWN SOURCE
---
name: silen-infra
description: "Work in silen's infrastructure: Twig (self-hosted Git and pull requests), Ino (release and Once deployment), and Info (Infomaniak DNS for silenlocatelli.ch and hodis.ch)."
---
# silen infra
This is the working map of the self-hosted stack. Read the section for the task
you are doing, then follow the repository's own `AGENTS.md` and `mise.toml`
when they are stricter. The `any` CLI installs this file at
`.opencode/skills/silen-infra/SKILL.md`.
## The map
| Thing | Location | What it is |
| --- | --- | --- |
| Twig server | <https://twig.silenlocatelli.ch> | Self-hosted Git server with a web UI and pull requests |
| Twig source | `https://twig.silenlocatelli.ch/twig/twig` | Rust/Actix-web server; repo for Twig itself |
| Ino source | `https://twig.silenlocatelli.ch/twig/ino` | Zig CLI for versions, releases, and Once deployments |
| Info | `https://twig.silenlocatelli.ch/silen/info` | OpenTofu/Terraform config for Infomaniak DNS |
| Any | `https://twig.silenlocatelli.ch/silen/any` | Small CLI that installs this skill into a repo |
| Deployment proxy | `proxy.silenlocatelli.ch` | Once/Kamal proxy in front of deployed apps |
| Ino deployment server | `https://ino.silenlocatelli.ch` | Once-compatible server Ino releases deploy to |
Repository paths on Twig are `{namespace}/{repo}`, for example `silen/info` or
`twig/ino`. HTTPS clones accept an optional `.git` suffix:
`https://twig.silenlocatelli.ch/silen/info.git`.
## Preferred project setup
When starting a project or reshaping an existing one, default to this shape:
- **Server-rendered UI first.** If the project has a server, render HTML on the
server and use **HTMX 4** for interaction. Add small vanilla JavaScript only
for what HTMX cannot do cleanly.
- **Vendor every asset.** CSS, HTMX, fonts, and any JavaScript library are
checked into the repository and served by the app itself. No CDNs, no remote
imports, and no runtime downloads.
- **A self-served pure JavaScript frontend is acceptable** when the app is
genuinely client-side. Serve the JS and CSS from the repository, and vendor
only libraries that are sensible for the task.
- **No unused vendor code.** Vendor only the files and features actually used;
remove dead JavaScript and unused library files. Do not ship a whole library
for one helper.
- **Keep vendored code intact.** Keep each library's license file next to it and
do not rewrite vendored sources; adapt your own code around them.
- **Degrade gracefully.** Prefer progressive enhancement: core reading and
navigation should still work if JavaScript fails.
## Twig: branches, pull requests, CI
**Prefer committing directly to `main`.** Push small, reviewed changes straight
to `main` instead of opening a pull request. Use a pull request only when the
user asks for one, when the change is large or risky, or when review is
genuinely useful. Twig does not require a PR (there are no required status
checks), so a PR is a collaboration choice, not a gate. The workflow below is
for the cases where a PR is wanted.
### Authenticate once
Create a personal access token in Twig under **Settings → Access tokens**. Grant
`view_namespace` for reading and `push_changes` for pushing, opening pull
requests, reviewing, and merging. For the Forgejo-compatible CLI:
```sh
fj --host https://twig.silenlocatelli.ch auth add-token
```
Twig also accepts the token directly:
```sh
export TWIG_TOKEN=... # never commit it
curl -fsS -H "Authorization: token $TWIG_TOKEN" \
https://twig.silenlocatelli.ch/api/v1/me
```
Git writes use HTTP Basic Auth. Use your Twig username and password, or the token
as the password. A credential helper keeps it out of the remote URL.
### Commit and push
For a normal small change, work on `main`:
```sh
git switch main
git pull
# edit, test, then:
git add -A
git commit -m "feat: add a subdomain for books"
git push
```
When a pull request is actually needed, branch from `main`:
```sh
git switch -c t3/<slug>
```
Use `t3/<slug>` for work started from a T3 Code thread; `feat/<slug>`,
`fix/<slug>`, or `docs/<slug>` are fine too. Keep one topic per branch. Twig
pull requests can only merge a branch from the **same repository** — forks are
not supported.
### Commit style
Use conventional commits; Ino reads them to choose a version bump.
```text
feat: add a subdomain for books
fix: reject stale branch heads
perf: cache rendered markdown
docs: explain Once labels
refactor: split the release parser
test: cover duplicate pull requests
chore: bump the Zig toolchain
feat!: drop the old config key
```
`!` or a `BREAKING CHANGE:` footer marks a breaking change. `feat` and `perf`
bump the minor version; everything else defaults to a patch.
### If you open a pull request
Only do this when a PR is preferred or requested. Push the branch first, then
create the request against `main`:
```sh
git push -u origin t3/<slug>
fj --host https://twig.silenlocatelli.ch pr create \
--base main \
--head t3/<slug> \
--title "feat: add books subdomain" \
--body "Adds the CNAME and the deployment label.
Verified with: mise run validate"
```
`fj pr create -A` fills the title and body from the commits. `--web` opens the
web form instead. Add `-r owner/repo` when the remote does not identify the
repository. Without `fj`, use the Forgejo-compatible API:
```sh
curl -fsS -X POST \
"https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls" \
-H "Authorization: token $TWIG_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg base main \
--arg head t3/<slug> \
--arg title 'feat: add books subdomain' \
--arg body 'Adds the CNAME and the deployment label.' \
'{base:$base, head:$head, title:$title, body:$body}')"
```
The response contains `number` and `html_url`. Open requests also appear in the
web UI under the repository's **Pull requests** tab. Every request has a
read-only ref `refs/pull/{number}/head`; do not push to `refs/pull/*`.
### Review and merge
```sh
fj --host https://twig.silenlocatelli.ch pr status <number> --wait
fj --host https://twig.silenlocatelli.ch pr view <number>
fj --host https://twig.silenlocatelli.ch pr checkout <number>
```
Approve or request changes through the review API (the `fj` build may only list
and request reviewers):
```sh
curl -fsS -X POST \
"https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls/<number>/reviews" \
-H "Authorization: token $TWIG_TOKEN" \
-H "Content-Type: application/json" \
-d '{"event":"APPROVED","body":"Checks pass."}'
```
`event` is `APPROVED`, `REQUEST_CHANGES`, or `COMMENT`. Merge with one of Twig's
three styles:
```sh
fj --host https://twig.silenlocatelli.ch pr merge <number> \
--method squash --delete
```
Twig also accepts `--method merge` and `--method rebase`. Updating a branch from
its base supports merge only; rebase updates are not offered.
### CI
A repository opts into Twig CI by committing `.twig/mise.toml`:
```toml
[tools]
rust = { version = "nightly-2026-10-31" }
"cargo-binstall" = "latest"
"cargo:cargo-nextest" = "latest"
[tasks.ci]
dir = ".."
run = ['cargo fmt --check', 'cargo clippy --all-targets', 'cargo nextest run']
```
Only `.twig/mise.toml` is used; a root `mise.toml` is not merged into a run.
Tasks execute from `.twig/` unless `dir = ".."`. A push queues one run per moved
branch; pull requests show the head commit's combined `ci` status. Statuses are
reported but **do not gate a merge**, so a green check is a convention, not a
server guarantee. CI must be enabled by the server operator (`TWIG_CI=1`) and
runs with the server user's filesystem access — treat it as trusted code.
Read runs and logs with `fj actions tasks` or
`GET /api/v1/repos/{owner}/{repo}/actions/tasks`. Dispatch manually with
`fj actions dispatch ci <branch>`.
### Twig repository config
`.twig.toml` at the repository root controls visibility and views:
```toml
private = true
deleteable = false
ignore_for_view = [".opencode/", "AGENTS.md", "docs/plans/"]
[scripts.install]
name = "Install"
scripts = [
{ name = "Install CLI", path = "scripts/install.sh", shell = "bash" },
]
```
`private = true` requires authentication even for reads. `deleteable = true` is
required before the UI/API can delete the repository. Keep secrets out of this
file and out of the repository.
### Twig limits worth remembering
- Pull requests are same-repository only; no forks.
- No labels, milestones, issues, projects, or thread resolution.
- No required status checks.
- No rebase updates for pull requests.
- Creating a private repository through the API is not supported; set
`private = true` in `.twig.toml`.
- Content writes are limited to 1 MiB; Git pushes and binary uploads to 512 MiB.
- API reads always require a token, even for public repositories.
## Ino: release and deploy
Ino is the Zig CLI that versions a project, pushes a Docker image, and asks the
Ino server to deploy it through Once.
### Install
```sh
git clone https://twig.silenlocatelli.ch/twig/ino
cd ino
mise run install # installs to ~/.local/bin, or $INO_PREFIX/bin
```
The install task removes a stale cargo-installed `ino` instead of shadowing it.
### Release
```sh
ino # same as `ino auto`: pick the bump from conventional commits
ino patch
ino minor
ino major
```
The release flow:
1. Reads the current version from `build.zig.zon` `.version` (preferred) or
`Cargo.toml` `[package].version`; if both exist, Zig wins.
2. Picks a bump: breaking → major, `feat`/`perf` → minor, else patch.
3. Updates `Cargo.toml` and the workspace `Cargo.lock` for Rust (the lockfile is
intentionally left out of the release commit), or `build.zig.zon` for Zig.
4. If a root `Dockerfile` exists, builds and pushes the versioned image and
`latest` with Docker Buildx. The Dockerfile must declare
`LABEL remote="owner/image"` and the registry login must already exist.
5. Commits and pushes the release. The branch needs a usable Git remote.
6. If both deployment labels are present, calls the Ino server and waits for the
app to report the requested image as running.
Use `ino new` to print all derived versions, and `ino exec <command...>` to run a
command with version environment variables injected (`INO_*` and `VERSION_*`).
### Container contract for a deployable app
The image must:
- Serve HTTP on `0.0.0.0:80`.
- Return a successful unauthenticated `GET /up`.
- Persist durable data under `/storage` (configure the app's real database and
upload paths to use it).
- Run the server as the foreground process (PID 1 behaviour), not a detached
background process.
Add both labels to the root `Dockerfile`; they must appear together:
```dockerfile
LABEL remote="silenloc/myapp" \
ino.deploy.server="https://ino.silenlocatelli.ch" \
ino.deploy.host="myapp.silenlocatelli.ch"
```
- `remote` is the actual registry repository.
- `ino.deploy.server` is the Ino server origin.
- `ino.deploy.host` is the public hostname. It must have a DNS record in the
Info repo (normally a CNAME to `proxy.silenlocatelli.ch`).
- Never put `INO_API_KEY`, registry passwords, or app secrets in labels.
The local release environment needs Docker Buildx, registry authentication,
Git push access, and a non-empty `INO_API_KEY`. The key is read from the local
environment only; it is not baked into the image.
### First deployment and day-two operations
For a brand-new app, release and create it with:
```sh
ino once remote create
```
For an app that already exists on the server, the normal `ino` release updates
it. Other Once operations:
```sh
ino once list
ino once deploy ghcr.io/owner/app:latest --host app.silenlocatelli.ch
ino once start app.silenlocatelli.ch
ino once stop app.silenlocatelli.ch
ino once exec app.silenlocatelli.ch sh
ino once update app.silenlocatelli.ch --image ghcr.io/owner/app:v2
ino once backup app.silenlocatelli.ch ./app-backup.tar.gz
ino once restore ./app-backup.tar.gz
ino once remove app.silenlocatelli.ch # keeps the data volume
ino once remove app.silenlocatelli.ch --remove-data
ino once keys reset app.silenlocatelli.ch --secret-key-base
```
Use `--registry-password-stdin` rather than putting a registry password in
shell history. `ino once` drives the local Docker daemon; it does not need the
upstream `once` executable.
### Deployment checks
Before calling a deployment done:
```sh
curl -fsS https://<host>/up
curl -fsS https://<host>/
```
Confirm the image tag the server reports matches the released version, and that
data written before a redeploy survives. A successful image build is not a
deployment.
## Info: DNS and subdomains
Info is an OpenTofu configuration for the Infomaniak DNS zones
`silenlocatelli.ch` and `hodis.ch`. The provider is `Infomaniak/infomaniak`
`~> 1.4.1`; the toolchain is `opentofu 1.13.0`.
```sh
git clone https://twig.silenlocatelli.ch/silen/info
cd info
mise install
mise run init
mise run plan
mise run apply # runs plan first
mise run fmt
mise run validate
```
`infomaniak_token` is a sensitive variable. Provide it through
`TF_VAR_infomaniak_token` or a local untracked file, and never commit a token.
Do not edit `infomaniak_api_*.json` by hand — it is a downloaded snapshot, not
the source of truth.
### Add a subdomain
Append a record to `records-silenlocatelli.tf` (or `records-hodis.tf` for
`hodis.ch`). New app subdomains normally point at the Once proxy:
```hcl
resource "infomaniak_record" "silenlocatelli_myapp_cname" {
zone_fqdn = infomaniak_zone.silenlocatelli.fqdn
source = "myapp"
type = "CNAME"
ttl = 3600
target = "proxy.silenlocatelli.ch"
}
```
Then:
```sh
mise run fmt
mise run plan # inspect the add
mise run apply
dig +short myapp.silenlocatelli.ch
```
Naming and address facts:
- `source` is relative to the zone: `myapp`, not `myapp.silenlocatelli.ch`.
- `silenlocatelli.ch` app subdomains normally CNAME to
`proxy.silenlocatelli.ch`.
- `proxy.silenlocatelli.ch` resolves to `83.228.212.88` (A) and
`2001:1600:18:102::17e` (AAAA).
- The `silenlocatelli.ch` apex is managed by Infomaniak nameservers and carries
mail/SPF/DMARC records; do not repoint it casually.
- `hodis.ch` currently has apex A/AAAA records pointing directly at the proxy.
- `fig.silenlocatelli.ch` has its own A/AAAA records, and `auth` points at
Auth0. Treat existing non-proxy records as intentional.
- Add an `import` block only when adopting a record that already exists in
Infomaniak; a newly created record needs none.
## Code quality before committing
Run the repository's own task first. It is the contract:
```sh
mise run verify
```
Then check the language-specific baseline below. A change that skips the repo's
formatter, linter, or tests is not ready to push.
### Rust
The Rust projects (Twig, Tree, Personal Page) pin a toolchain and use the same
verify shape:
```sh
cargo fmt --check
cargo clippy --all-targets
cargo nextest run
```
- Keep the pinned `rust-toolchain.toml` channel; bump it deliberately in its own
commit.
- Treat Clippy warnings as defects. Fix the code; do not add a blanket
`#[allow(...)]`.
- Use `Result` and `?` for fallible paths. Keep `unwrap`/`expect` out of request
handlers and startup paths; tests may use them.
- Prefer clear ownership and borrowing over cloning to silence the borrow
checker.
- Keep `Cargo.lock` committed for binary projects.
- Twig-specific: do not eagerly connect to the SQLite file; follow the existing
lazy connection pattern.
- Run tests that touch HTTP, Git, or database code against the real
`mise run verify` task, not only `cargo check`.
### Zig
The Zig projects (Ino, Any) use:
```sh
zig fmt --check build.zig src
zig build test
zig build -Doptimize=ReleaseSafe
```
- Use only the Zig standard library unless the project already vendored an
approved dependency; do not add packages casually.
- Let the test allocator catch leaks. Free or arena-allocate every allocation,
and use `errdefer`/`defer` on error paths.
- Return errors for bad input; do not use `catch unreachable` or `unreachable`
on user-controlled data.
- Keep `@embedFile` payloads and build options declared in `build.zig` so tests
compile with the same inputs.
- Tests live beside the code in `test` blocks, and pure parsing/composition
logic is preferred over tests that depend on the process cwd.
- Formatting is `zig fmt`; do not hand-align code against it.
### JavaScript
The web assets in Twig are deliberately dependency-free browser JavaScript: no
bundler, no npm build step, and vendored libraries are left untouched.
- Put new browser code in its own file under `assets/` and wrap it in an IIFE
with `"use strict"`; do not leak globals.
- Match the surrounding style (`var`/`function` in older files, semicolons,
the file's indentation). Do not reformat a whole file for a small change.
- Guard browser APIs that can throw or be unavailable, especially
`localStorage` and `sessionStorage`, with `try`/`catch`.
- Use `textContent` for untrusted text and sanitize rendered HTML; Twig vendors
DOMPurify for this. Never interpolate untrusted values into `innerHTML`.
- Use event delegation for repeated controls and clean up listeners with the
element's lifecycle.
- Handle rejected promises; do not leave a floating async call without a
`catch`.
- If a repository does have `package.json`, run its own formatter, linter,
typecheck, and tests (`mise run verify` first), and ask before adding a
dependency.
- Use **Bun**, not Node, for JavaScript tooling: `bun install`, `bun run`, and
`bun test`. Do not use `node` or `npm` to run or check project code.
- With no tooling, at minimum run `bun build --no-bundle <file>` for syntax and
exercise the page in a browser.
### Universal change hygiene
- Keep the diff focused; split unrelated refactors into their own commit or PR.
- Update docs, `.twig.toml`, `mise.toml`, and deployment labels when behaviour
changes.
- Do not commit `.env`, tokens, registry passwords, DNS credentials, or build
outputs.
- Re-read `git diff` before pushing, and say what was verified in the commit
message or PR description.
- If a check cannot run, say so explicitly instead of claiming success.
name: silen-infra description: "Work in silen's infrastructure: Twig (self-hosted Git and pull requests), Ino (release and Once deployment), and Info (Infomaniak DNS for silenlocatelli.ch and hodis.ch)."
silen infra
This is the working map of the self-hosted stack. Read the section for the task
you are doing, then follow the repository's own AGENTS.md and mise.toml
when they are stricter. The any CLI installs this file at
.opencode/skills/silen-infra/SKILL.md.
The map
| Thing | Location | What it is |
|---|---|---|
| Twig server | https://twig.silenlocatelli.ch | Self-hosted Git server with a web UI and pull requests |
| Twig source | https://twig.silenlocatelli.ch/twig/twig | Rust/Actix-web server; repo for Twig itself |
| Ino source | https://twig.silenlocatelli.ch/twig/ino | Zig CLI for versions, releases, and Once deployments |
| Info | https://twig.silenlocatelli.ch/silen/info | OpenTofu/Terraform config for Infomaniak DNS |
| Any | https://twig.silenlocatelli.ch/silen/any | Small CLI that installs this skill into a repo |
| Deployment proxy | proxy.silenlocatelli.ch | Once/Kamal proxy in front of deployed apps |
| Ino deployment server | https://ino.silenlocatelli.ch | Once-compatible server Ino releases deploy to |
Repository paths on Twig are {namespace}/{repo}, for example silen/info or
twig/ino. HTTPS clones accept an optional .git suffix:
https://twig.silenlocatelli.ch/silen/info.git.
Preferred project setup
When starting a project or reshaping an existing one, default to this shape:
- Server-rendered UI first. If the project has a server, render HTML on the server and use HTMX 4 for interaction. Add small vanilla JavaScript only for what HTMX cannot do cleanly.
- Vendor every asset. CSS, HTMX, fonts, and any JavaScript library are checked into the repository and served by the app itself. No CDNs, no remote imports, and no runtime downloads.
- A self-served pure JavaScript frontend is acceptable when the app is genuinely client-side. Serve the JS and CSS from the repository, and vendor only libraries that are sensible for the task.
- No unused vendor code. Vendor only the files and features actually used; remove dead JavaScript and unused library files. Do not ship a whole library for one helper.
- Keep vendored code intact. Keep each library's license file next to it and do not rewrite vendored sources; adapt your own code around them.
- Degrade gracefully. Prefer progressive enhancement: core reading and navigation should still work if JavaScript fails.
Twig: branches, pull requests, CI
Prefer committing directly to main. Push small, reviewed changes straight
to main instead of opening a pull request. Use a pull request only when the
user asks for one, when the change is large or risky, or when review is
genuinely useful. Twig does not require a PR (there are no required status
checks), so a PR is a collaboration choice, not a gate. The workflow below is
for the cases where a PR is wanted.
Authenticate once
Create a personal access token in Twig under Settings → Access tokens. Grant
view_namespace for reading and push_changes for pushing, opening pull
requests, reviewing, and merging. For the Forgejo-compatible CLI:
fj --host https://twig.silenlocatelli.ch auth add-token
Twig also accepts the token directly:
export TWIG_TOKEN=... # never commit it
curl -fsS -H "Authorization: token $TWIG_TOKEN" \
https://twig.silenlocatelli.ch/api/v1/me
Git writes use HTTP Basic Auth. Use your Twig username and password, or the token as the password. A credential helper keeps it out of the remote URL.
Commit and push
For a normal small change, work on main:
git switch main
git pull
# edit, test, then:
git add -A
git commit -m "feat: add a subdomain for books"
git push
When a pull request is actually needed, branch from main:
git switch -c t3/<slug>
Use t3/<slug> for work started from a T3 Code thread; feat/<slug>,
fix/<slug>, or docs/<slug> are fine too. Keep one topic per branch. Twig
pull requests can only merge a branch from the same repository — forks are
not supported.
Commit style
Use conventional commits; Ino reads them to choose a version bump.
feat: add a subdomain for books
fix: reject stale branch heads
perf: cache rendered markdown
docs: explain Once labels
refactor: split the release parser
test: cover duplicate pull requests
chore: bump the Zig toolchain
feat!: drop the old config key
! or a BREAKING CHANGE: footer marks a breaking change. feat and perf
bump the minor version; everything else defaults to a patch.
If you open a pull request
Only do this when a PR is preferred or requested. Push the branch first, then
create the request against main:
git push -u origin t3/<slug>
fj --host https://twig.silenlocatelli.ch pr create \
--base main \
--head t3/<slug> \
--title "feat: add books subdomain" \
--body "Adds the CNAME and the deployment label.
Verified with: mise run validate"
fj pr create -A fills the title and body from the commits. --web opens the
web form instead. Add -r owner/repo when the remote does not identify the
repository. Without fj, use the Forgejo-compatible API:
curl -fsS -X POST \
"https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls" \
-H "Authorization: token $TWIG_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg base main \
--arg head t3/<slug> \
--arg title 'feat: add books subdomain' \
--arg body 'Adds the CNAME and the deployment label.' \
'{base:$base, head:$head, title:$title, body:$body}')"
The response contains number and html_url. Open requests also appear in the
web UI under the repository's Pull requests tab. Every request has a
read-only ref refs/pull/{number}/head; do not push to refs/pull/*.
Review and merge
fj --host https://twig.silenlocatelli.ch pr status <number> --wait
fj --host https://twig.silenlocatelli.ch pr view <number>
fj --host https://twig.silenlocatelli.ch pr checkout <number>
Approve or request changes through the review API (the fj build may only list
and request reviewers):
curl -fsS -X POST \
"https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls/<number>/reviews" \
-H "Authorization: token $TWIG_TOKEN" \
-H "Content-Type: application/json" \
-d '{"event":"APPROVED","body":"Checks pass."}'
event is APPROVED, REQUEST_CHANGES, or COMMENT. Merge with one of Twig's
three styles:
fj --host https://twig.silenlocatelli.ch pr merge <number> \
--method squash --delete
Twig also accepts --method merge and --method rebase. Updating a branch from
its base supports merge only; rebase updates are not offered.
CI
A repository opts into Twig CI by committing .twig/mise.toml:
[tools]
rust = { version = "nightly-2026-10-31" }
"cargo-binstall" = "latest"
"cargo:cargo-nextest" = "latest"
[tasks.ci]
dir = ".."
run = ['cargo fmt --check', 'cargo clippy --all-targets', 'cargo nextest run']
Only .twig/mise.toml is used; a root mise.toml is not merged into a run.
Tasks execute from .twig/ unless dir = "..". A push queues one run per moved
branch; pull requests show the head commit's combined ci status. Statuses are
reported but do not gate a merge, so a green check is a convention, not a
server guarantee. CI must be enabled by the server operator (TWIG_CI=1) and
runs with the server user's filesystem access — treat it as trusted code.
Read runs and logs with fj actions tasks or
GET /api/v1/repos/{owner}/{repo}/actions/tasks. Dispatch manually with
fj actions dispatch ci <branch>.
Twig repository config
.twig.toml at the repository root controls visibility and views:
private = true
deleteable = false
ignore_for_view = [".opencode/", "AGENTS.md", "docs/plans/"]
[scripts.install]
name = "Install"
scripts = [
{ name = "Install CLI", path = "scripts/install.sh", shell = "bash" },
]
private = true requires authentication even for reads. deleteable = true is
required before the UI/API can delete the repository. Keep secrets out of this
file and out of the repository.
Twig limits worth remembering
- Pull requests are same-repository only; no forks.
- No labels, milestones, issues, projects, or thread resolution.
- No required status checks.
- No rebase updates for pull requests.
- Creating a private repository through the API is not supported; set
private = truein.twig.toml. - Content writes are limited to 1 MiB; Git pushes and binary uploads to 512 MiB.
- API reads always require a token, even for public repositories.
Ino: release and deploy
Ino is the Zig CLI that versions a project, pushes a Docker image, and asks the Ino server to deploy it through Once.
Install
git clone https://twig.silenlocatelli.ch/twig/ino
cd ino
mise run install # installs to ~/.local/bin, or $INO_PREFIX/bin
The install task removes a stale cargo-installed ino instead of shadowing it.
Release
ino # same as `ino auto`: pick the bump from conventional commits
ino patch
ino minor
ino major
The release flow:
- Reads the current version from
build.zig.zon.version(preferred) orCargo.toml[package].version; if both exist, Zig wins. - Picks a bump: breaking → major,
feat/perf→ minor, else patch. - Updates
Cargo.tomland the workspaceCargo.lockfor Rust (the lockfile is intentionally left out of the release commit), orbuild.zig.zonfor Zig. - If a root
Dockerfileexists, builds and pushes the versioned image andlatestwith Docker Buildx. The Dockerfile must declareLABEL remote="owner/image"and the registry login must already exist. - Commits and pushes the release. The branch needs a usable Git remote.
- If both deployment labels are present, calls the Ino server and waits for the app to report the requested image as running.
Use ino new to print all derived versions, and ino exec <command...> to run a
command with version environment variables injected (INO_* and VERSION_*).
Container contract for a deployable app
The image must:
- Serve HTTP on
0.0.0.0:80. - Return a successful unauthenticated
GET /up. - Persist durable data under
/storage(configure the app's real database and upload paths to use it). - Run the server as the foreground process (PID 1 behaviour), not a detached background process.
Add both labels to the root Dockerfile; they must appear together:
LABEL remote="silenloc/myapp" \
ino.deploy.server="https://ino.silenlocatelli.ch" \
ino.deploy.host="myapp.silenlocatelli.ch"
remoteis the actual registry repository.ino.deploy.serveris the Ino server origin.ino.deploy.hostis the public hostname. It must have a DNS record in the Info repo (normally a CNAME toproxy.silenlocatelli.ch).- Never put
INO_API_KEY, registry passwords, or app secrets in labels.
The local release environment needs Docker Buildx, registry authentication,
Git push access, and a non-empty INO_API_KEY. The key is read from the local
environment only; it is not baked into the image.
First deployment and day-two operations
For a brand-new app, release and create it with:
ino once remote create
For an app that already exists on the server, the normal ino release updates
it. Other Once operations:
ino once list
ino once deploy ghcr.io/owner/app:latest --host app.silenlocatelli.ch
ino once start app.silenlocatelli.ch
ino once stop app.silenlocatelli.ch
ino once exec app.silenlocatelli.ch sh
ino once update app.silenlocatelli.ch --image ghcr.io/owner/app:v2
ino once backup app.silenlocatelli.ch ./app-backup.tar.gz
ino once restore ./app-backup.tar.gz
ino once remove app.silenlocatelli.ch # keeps the data volume
ino once remove app.silenlocatelli.ch --remove-data
ino once keys reset app.silenlocatelli.ch --secret-key-base
Use --registry-password-stdin rather than putting a registry password in
shell history. ino once drives the local Docker daemon; it does not need the
upstream once executable.
Deployment checks
Before calling a deployment done:
curl -fsS https://<host>/up
curl -fsS https://<host>/
Confirm the image tag the server reports matches the released version, and that data written before a redeploy survives. A successful image build is not a deployment.
Info: DNS and subdomains
Info is an OpenTofu configuration for the Infomaniak DNS zones
silenlocatelli.ch and hodis.ch. The provider is Infomaniak/infomaniak
~> 1.4.1; the toolchain is opentofu 1.13.0.
git clone https://twig.silenlocatelli.ch/silen/info
cd info
mise install
mise run init
mise run plan
mise run apply # runs plan first
mise run fmt
mise run validate
infomaniak_token is a sensitive variable. Provide it through
TF_VAR_infomaniak_token or a local untracked file, and never commit a token.
Do not edit infomaniak_api_*.json by hand — it is a downloaded snapshot, not
the source of truth.
Add a subdomain
Append a record to records-silenlocatelli.tf (or records-hodis.tf for
hodis.ch). New app subdomains normally point at the Once proxy:
resource "infomaniak_record" "silenlocatelli_myapp_cname" {
zone_fqdn = infomaniak_zone.silenlocatelli.fqdn
source = "myapp"
type = "CNAME"
ttl = 3600
target = "proxy.silenlocatelli.ch"
}
Then:
mise run fmt
mise run plan # inspect the add
mise run apply
dig +short myapp.silenlocatelli.ch
Naming and address facts:
sourceis relative to the zone:myapp, notmyapp.silenlocatelli.ch.silenlocatelli.chapp subdomains normally CNAME toproxy.silenlocatelli.ch.proxy.silenlocatelli.chresolves to83.228.212.88(A) and2001:1600:18:102::17e(AAAA).- The
silenlocatelli.chapex is managed by Infomaniak nameservers and carries mail/SPF/DMARC records; do not repoint it casually. hodis.chcurrently has apex A/AAAA records pointing directly at the proxy.fig.silenlocatelli.chhas its own A/AAAA records, andauthpoints at Auth0. Treat existing non-proxy records as intentional.- Add an
importblock only when adopting a record that already exists in Infomaniak; a newly created record needs none.
Code quality before committing
Run the repository's own task first. It is the contract:
mise run verify
Then check the language-specific baseline below. A change that skips the repo's formatter, linter, or tests is not ready to push.
Rust
The Rust projects (Twig, Tree, Personal Page) pin a toolchain and use the same verify shape:
cargo fmt --check
cargo clippy --all-targets
cargo nextest run
- Keep the pinned
rust-toolchain.tomlchannel; bump it deliberately in its own commit. - Treat Clippy warnings as defects. Fix the code; do not add a blanket
#[allow(...)]. - Use
Resultand?for fallible paths. Keepunwrap/expectout of request handlers and startup paths; tests may use them. - Prefer clear ownership and borrowing over cloning to silence the borrow checker.
- Keep
Cargo.lockcommitted for binary projects. - Twig-specific: do not eagerly connect to the SQLite file; follow the existing lazy connection pattern.
- Run tests that touch HTTP, Git, or database code against the real
mise run verifytask, not onlycargo check.
Zig
The Zig projects (Ino, Any) use:
zig fmt --check build.zig src
zig build test
zig build -Doptimize=ReleaseSafe
- Use only the Zig standard library unless the project already vendored an approved dependency; do not add packages casually.
- Let the test allocator catch leaks. Free or arena-allocate every allocation,
and use
errdefer/deferon error paths. - Return errors for bad input; do not use
catch unreachableorunreachableon user-controlled data. - Keep
@embedFilepayloads and build options declared inbuild.zigso tests compile with the same inputs. - Tests live beside the code in
testblocks, and pure parsing/composition logic is preferred over tests that depend on the process cwd. - Formatting is
zig fmt; do not hand-align code against it.
JavaScript
The web assets in Twig are deliberately dependency-free browser JavaScript: no bundler, no npm build step, and vendored libraries are left untouched.
- Put new browser code in its own file under
assets/and wrap it in an IIFE with"use strict"; do not leak globals. - Match the surrounding style (
var/functionin older files, semicolons, the file's indentation). Do not reformat a whole file for a small change. - Guard browser APIs that can throw or be unavailable, especially
localStorageandsessionStorage, withtry/catch. - Use
textContentfor untrusted text and sanitize rendered HTML; Twig vendors DOMPurify for this. Never interpolate untrusted values intoinnerHTML. - Use event delegation for repeated controls and clean up listeners with the element's lifecycle.
- Handle rejected promises; do not leave a floating async call without a
catch. - If a repository does have
package.json, run its own formatter, linter, typecheck, and tests (mise run verifyfirst), and ask before adding a dependency. - Use Bun, not Node, for JavaScript tooling:
bun install,bun run, andbun test. Do not usenodeornpmto run or check project code. - With no tooling, at minimum run
bun build --no-bundle <file>for syntax and exercise the page in a browser.
Universal change hygiene
- Keep the diff focused; split unrelated refactors into their own commit or PR.
- Update docs,
.twig.toml,mise.toml, and deployment labels when behaviour changes. - Do not commit
.env, tokens, registry passwords, DNS credentials, or build outputs. - Re-read
git diffbefore pushing, and say what was verified in the commit message or PR description. - If a check cannot run, say so explicitly instead of claiming success.