- Go 75%
- JavaScript 14.5%
- CSS 4.5%
- Python 4.2%
- HTML 0.9%
- Other 0.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| cmd | ||
| deploy/kubernetes | ||
| design | ||
| docs | ||
| examples | ||
| internal | ||
| scripts | ||
| .dockerignore | ||
| .gitignore | ||
| BUILDING-THIN-APPS-v0.4.md | ||
| compose.blobs.yaml | ||
| compose.dev.yaml | ||
| compose.yaml | ||
| Dockerfile | ||
| Dockerfile.dev | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| TRELLIS-v0.7.md | ||
| trellisapp.yaml | ||
Trellis
Trellis is a Go shared-state service for thin applications, based on TRELLIS v0.7. Stored JSON, ephemeral live values, Garage/NAS blobs and SSE watches work across replicas sharing PostgreSQL. Automatic economic storage optimization and an OIDC-secured administrative control plane are implemented; configurable HTTP publication and a trusted browser identity boundary are implemented. The generic router can host complete static websites from stored values and blobs, with host-specific roots, directory indexes and opt-in SPA fallback. Native Authelia OIDC and platform asset bootstrap are implemented; actual cluster/Authelia/ingress integration still requires deployment verification. See status.
Trellis is licensed under GPL-2.0-only; see LICENSE.
The data engine provides authorized leaf/branch reads, flat/tree pagination, conditional writes, atomic stored/blob transactions, durable idempotency, schema and path validation, recursive deletion, live claims/expiry and watch replay/reset. Architecture, the optimizer and the phase-two protocol explain the consistency and failure behavior.
Develop a thin app locally
docker build -t trellis-dev -f Dockerfile.dev .
docker run --rm --name trellis-local -p 127.0.0.1:8080:8080 trellis-dev
Open http://localhost:8080/ for the real Trellis admin panel, /_dev/ to switch people,
using a simulated local administrator. PostgreSQL and hot/cold storage start inside
the container. The optional example requires TRELLIS_DEV_EXAMPLE=1; it is not
the default entry point.
For your own upstream, manifest, host networking, volumes and token files, follow
the exact Phase 6 commands. No host Trellis binary is required.
Run the lower-level engine harness
Use the Go version in go.mod and PostgreSQL 17 or newer (tests use PostgreSQL 18).
Start the supplied local database, validate configuration and build both binaries:
docker compose up -d --wait postgres
export TRELLIS_DATABASE_URL='postgres://trellis:trellis-local@127.0.0.1:5432/trellis?sslmode=disable'
make check build dev
./bin/trellis migrate
TRELLIS_MODE=dev ./bin/trellis-dev serve
The development binary listens on service port 8081, private peer port
8082, and health/metrics port 9090, all on 127.0.0.1. It accepts
Authorization: Bearer dev:tierlist through a development-only authenticator.
The authorization engine, storage, live protocol and API are identical to the
production implementation. This host binary remains the lower-level service harness; the Docker development
package above supplies the complete proxy/person-switcher and managed PostgreSQL.
Upgrading phase one: stop the old stored-only writers, run migrate, then
start the new binary. The example now grants acting live access. If the database
has the previous example's digest and every replica is stopped, explicitly
activate the updated configuration before serving:
# Read the current digest using your database administration tools:
psql "$TRELLIS_DATABASE_URL" -Atc 'SELECT digest FROM trellis_config'
./bin/trellis activate --expected-digest='<the digest printed above>'
Offline activation checks the exact previous digest and refuses active peers or persistent kind changes. Fresh databases need no activation command. Online configuration edits use the existing atomic file reload and check live kinds too.
Administrative web interface
The optional admin listener uses Authelia OIDC with PKCE and requires current
admins membership on every protected request. It provides a real data explorer,
conditional JSON/live edits, resumable blob uploads, storage controls, configuration
inspection, audit browsing and a versioned operator asset catalog.
Apply migrations through 008 and configure the dedicated private listener, HTTPS public
origin, issuer, client secret and shared session encryption key. There is no
production header/dev-token fallback. See Phase 5 setup and
the administrative security boundary. Trellis serves bootstrap /lt/ files itself and configured publication routes
can replace them. See production integration and required resources.
Try stored data
Create a list and its first membership atomically in audit mode:
curl --fail-with-body http://127.0.0.1:8081/v1/tx \
-H 'Authorization: Bearer dev:tierlist' \
-H 'Trellis-Audit-As: u01j00000000000000000000002' \
-H 'Idempotency-Key: example-create-list' \
-H 'Content-Type: application/json' \
--data '{"ops":[
{"op":"put","path":"core.tierlist.lists.01j00000000000000000000000.meta.title","value":"Best bosses","if":{"absent":true}},
{"op":"put","path":"core.tierlist.lists.01j00000000000000000000000.members.u01j00000000000000000000002","value":{"role":"owner"},"if":{"absent":true}}
]}'
Read as that person, or add ?shape=tree, depth, limit and cursor:
curl --fail-with-body \
-H 'Authorization: Bearer dev:tierlist' \
-H 'Trellis-Act-As: u01j00000000000000000000002' \
http://127.0.0.1:8081/v1/data/core.tierlist.lists.01j00000000000000000000000
Replace a stored value with its current revision. Reuse the idempotency key when retrying the same action, including the original body and precondition:
curl --fail-with-body -X PUT \
-H 'Authorization: Bearer dev:tierlist' \
-H 'Trellis-Act-As: u01j00000000000000000000002' \
-H 'Content-Type: application/json' \
-H 'If-Match: "1"' -H 'Idempotency-Key: example-rename-list' \
--data '{"value":"Favorite bosses"}' \
http://127.0.0.1:8081/v1/data/core.tierlist.lists.01j00000000000000000000000.meta.title
Stored DELETE requires If-Match and an idempotency key. A branch DELETE with
?recursive=1 requires delete permission on every leaf and a key; it needs no
revision and changes nothing if any leaf fails admission. Transactions accept
stored operations/checks only and return indexed failures.
Try live values and watches
Open a watch in one terminal. Reconnect with Last-Event-ID or since to replay
stored events. A reset means read the subtree again and watch without a resume
point. Live events have no replay sequence; reread live values after reconnecting.
curl -N --fail-with-body \
-H 'Authorization: Bearer dev:tierlist' \
-H 'Trellis-Act-As: u01j00000000000000000000002' \
'http://127.0.0.1:8081/v1/watch?path=core.tierlist.lists.01j00000000000000000000000'
In another terminal, publish a cursor. It expires automatically after five seconds
and the watch receives the put and expiry. Live requests need no idempotency key
or precondition. If-None-Match: * creates an exclusive claim, and If-Match
refreshes only the current revision. A failed condition returns 412.
curl --fail-with-body -X PUT \
-H 'Authorization: Bearer dev:tierlist' \
-H 'Trellis-Act-As: u01j00000000000000000000002' \
-H 'Content-Type: application/json' \
--data '{"value":{"x":0.2,"y":0.5},"ttl":"5s"}' \
http://127.0.0.1:8081/v1/data/core.tierlist.lists.01j00000000000000000000000.live.cursors.u01j00000000000000000000002
Live JSON remains only in replica memory. A restarted replica fetches it from a survivor; losing every memory copy clears live values. A dead peer may stall live writes for its five-second lease; synchronized stored requests continue. Peer HTTP partitions fail closed rather than allowing conflicting local writes.
Run three instances
Stop the single instance first, then run:
make multi
This starts separate processes with service ports 8081, 8181, 8281, peer ports 8082, 8182, 8282 and health ports 9090, 9190, 9290. Write through one service port and read/watch through another. Ctrl-C stops all three. Every instance uses the same configuration and database. There is no sticky routing or request leader.
Development fixture identities have fixed assigned opaque segments:
| Person | Segment | Groups |
|---|---|---|
| John | u01j00000000000000000000001 |
family |
| Anna | u01j00000000000000000000002 |
family |
| Admin | u01j00000000000000000000003 |
family, admins |
The Admin fixture does not grant unrestricted platform administration. There is no admin application route. See the separate administrative boundary.
Configure and operate
Subcommands include serve, migrate, check-schema, check, storage initialization/
preflight and operator-only activate. check-schema needs only PostgreSQL and
is used by production startup gates. Serving
checks the schema; migrations run separately and are transactional/repeatable.
Production uses native Kubernetes TrellisApps as its sole registration source.
Use the complete first-deployment guide, or
install CRD/RBAC and follow the migration instructions.
Development retains complete registry/resource directories without a cluster.
| Setting | Default / purpose |
|---|---|
TRELLIS_DATABASE_URL / _FILE |
PostgreSQL primary; default mounted secret /run/secrets/trellis/database-url |
TRELLIS_CONFIG_SOURCE / --config-source |
kubernetes in production, files in development |
TRELLIS_REGISTRY / --registry |
examples/registry |
TRELLIS_APPS / --apps |
examples/apps |
TRELLIS_LISTEN / --listen |
127.0.0.1:8081; service API |
TRELLIS_HEALTH_LISTEN / --health-listen |
127.0.0.1:9090 |
TRELLIS_PEER_LISTEN / --peer-listen |
127.0.0.1:8082; private replica RPC |
TRELLIS_PEER_URL |
Advertised URL reachable by every replica; defaults to bound address |
TRELLIS_PEER_KEY |
Production requires at least 32 secret bytes, shared by replicas |
TRELLIS_PEER_TLS_CERT, TRELLIS_PEER_TLS_KEY |
Peer serving certificate/key; both required for HTTPS |
TRELLIS_PEER_CA |
Optional additional CA for verified peer HTTPS |
TRELLIS_KUBERNETES_API |
Discovered in-cluster; HTTPS override supported |
TRELLIS_KUBERNETES_CA |
/var/run/secrets/kubernetes.io/serviceaccount/ca.crt |
TRELLIS_KUBERNETES_TOKEN_FILE |
/var/run/secrets/kubernetes.io/serviceaccount/token |
The table lists bare-binary defaults; the production image supplies Kubernetes listener/path defaults described in production integration. Mounted-secret and OIDC settings are documented there too.
Non-loopback peer URLs require HTTPS. Restrict peer/service/health listeners using
network policy; never route peer RPC through a public app hostname. The development
build refuses non-loopback binds and has a development-only loopback peer key.
Production app tokens use Kubernetes TokenReview with audience trellis and
registry service-account matching. Trellis needs create permission on
authentication.k8s.io/tokenreviews; reviewer credentials are reread each call.
Production supports System/Audit and acting requests. Native browser OIDC
sessions resolve immutable subjects/current groups without a custom directory;
acting requests require a current authenticated grant and otherwise fail closed.
Remote-User alone can never establish stable person identity.
The elected embedded controller watches TrellisApps, reports status, and publishes validated snapshots through PostgreSQL. Replicas follow that shared registry; stale replicas become unready until they load the active digest. Invalid updates retain the last valid generation, and deletion preserves stored values and blobs. Explicit file mode polls complete directories every two seconds; use atomic directory updates and synchronize all file-backed replicas.
Liveness is independent of PostgreSQL; readiness checks the database/digest and
returns 503 while draining. SIGTERM closes SSE streams promptly and drains
ordinary requests before closing pools and peer membership. Logs omit values,
credentials and emails. Basic request/error counters are exposed on /metrics.
./bin/trellis check --registry ./registry/apps --apps ./deploy/trellisapps
curl http://127.0.0.1:9090/healthz
curl http://127.0.0.1:9090/readyz
curl http://127.0.0.1:9090/metrics
Verify
make test vet check
# Integration tests create isolated schemas; use a disposable database/role.
export TRELLIS_TEST_DATABASE_URL="$TRELLIS_DATABASE_URL"
make integration
go test -race -tags trellisdev ./...
go test ./internal/tree -run '^$' -fuzz FuzzParse -fuzztime 5s
go test ./internal/tree -run '^$' -fuzz FuzzPattern -fuzztime 5s
Without the test URL, database tests explicitly skip; make integration requires
it. The full integration suite includes a separate-process crash/restart/SSE
failure drill lasting over 25 seconds. Use go test -short to skip that drill
while retaining the database/peer tests. No SQL driver or peer transport is mocked.
See phase-two validation for coverage and limits.
Blob storage
See Phase 3 byte storage and Phase 4 optimization for protocols, accounting, dynamic discovery and recovery. Initialize a shared durable NAS mount once, then configure the same directory on every replica:
./bin/trellis init-blob-store /mnt/nas/trellis
export TRELLIS_BLOB_COLD_DIRECTORY=/mnt/nas/trellis
# No manual total capacity is required; NAS capacity is discovered.
For local development, use an initialized directory under your project instead. The filesystem must support hard links and durable file/directory fsync. Trellis fails closed if the mount marker is missing. A pod-local directory is suitable only for tests, never for authoritative production upload staging.
Connect an existing Garage bucket with scoped read/write/list/delete and multipart permissions. Region and endpoint must match Garage; TLS uses system roots or TRELLIS_GARAGE_CA for a private CA:
export TRELLIS_GARAGE_ENDPOINT=https://garage.example.internal
export TRELLIS_GARAGE_BUCKET=trellis
export TRELLIS_GARAGE_REGION=garage
export TRELLIS_GARAGE_ACCESS_KEY='<access key>'
export TRELLIS_GARAGE_SECRET_KEY='<secret key>'
export TRELLIS_GARAGE_PREFIX=trellis
export TRELLIS_GARAGE_ADMIN_ENDPOINT=https://garage-admin.example.internal
export TRELLIS_GARAGE_ADMIN_TOKEN_FILE=/run/secrets/garage-read-only-token
The Garage admin token needs only GetClusterStatus,GetClusterLayout,GetClusterHealth
scopes. Trellis inspects the native layout, replication, node health and physical
filesystem space; it does not alter Garage configuration. Native discovery is the
default, with 10% filesystem safety reserves. Observations older than 60 seconds
fail closed. No external capacity JSON file or Kubernetes collector is required.
The existing private CA setting applies to both S3 and admin TLS.
The initial v0.5 hot allocation is 300 GiB, bounded by real safe capacity. Change it live, or remove the optional allocation while retaining physical limits:
./bin/trellis storage-limit --tier hot --bytes 107374182400 # 100 GiB
./bin/trellis storage-limit --tier cold --bytes unlimited
./bin/trellis storage-status
./bin/trellis storage-explain # dry evaluation, no mutations or transfers
./bin/trellis storage-cancel --migration '<id>'
make simulate
These operator commands use database/host credentials and are absent from the application API. Legacy HOT/COLD_CAPACITY environment settings initialize a cap only when its database row does not exist; subsequent CLI updates win on restart. Tiered uploads use the v0.5 economic score before receiving content. Large objects can start directly on NAS. The global optimizer tracks actual access, plans every 15 minutes/material capacity change and migrates with hysteresis, quotas, safety graces and globally leased workers. Two workers share a 25 MiB/s transfer budget. TRELLIS_BLOB_HOT_DIRECTORY supplies a filesystem fixture instead of Garage.
After bootstrapping the existing tierlist example membership, a direct upload is:
curl -H 'Authorization: Bearer dev:tierlist' \
-H 'Trellis-Act-As: u01j00000000000000000000002' \
-H 'Idempotency-Key: blob-example-1' -H 'If-None-Match: *' \
-H 'Content-Type: image/png' -H 'Trellis-Filename: image.png' \
--upload-file image.png \
http://127.0.0.1:8081/v1/data/core.tierlist.lists.a.entries.u01j00000000000000000000002.i1.image
Download the same URL for bytes, add ?meta=1 for its stub, or send a Range header.
Large files use tus POST/HEAD/PATCH at /v1/uploads, followed by conditional PUT
{"upload":"<id>"} or put-blob in /v1/tx. Use chunks no larger than 64 MiB.
For a real, isolated Garage test environment:
make blob-fixture
export TRELLIS_TEST_DATABASE_URL='postgres://trellis:trellis-local@127.0.0.1:5432/trellis?sslmode=disable'
make blob-tests
# Stop the fixture when finished; its volume persists until explicitly removed.
docker compose -f compose.blobs.yaml down
The fixture binds only loopback and uses development credentials. It is independent of your production Garage. For manual hot admissions against it, supply a fresh local capacity observation and the fixture credentials from compose.blobs.yaml. Upgrade existing Phase 2 installations by applying migration 003 and replacing all old replicas before enabling blob traffic. Phase 4 adds migration 004; replace Phase 3 writers before enabling optimization. See PHASE-4.md for calibration and real hardware checks that the local fixture cannot establish.
Shared fonts and licenses
Trellis serves /fonts/ and /lt/fonts/ from core.shared.fonts, and /licenses/
from core.shared.licenses. Other /lt/ resources proxy to the configured
source-managed asset service. See exact route-to-leaf mappings and local commands.
Configurable HTTP resources (v0.7)
The admin HTTP resources tab manages host-aware exact/prefix routes and stable aliases to existing stored/blob leaves. Public publication requires a separate platform registry approval; protected reads use the normal app/person authorization engine. Git configuration remains read-only in the admin UI. See HTTP resources, identity and upgrade for configuration, reversible filename mapping, ingress forwarding, manifest-only platform ownership, trusted immutable identity, development behavior and migrations 007–008. Existing audit fixes and physical blob keys are preserved.
External device authentication
Admin Devices registers independent device identities and issues expiring
one-time bearer credentials. Explicit devices grants in the owning TrellisApp
use the same authorization engine; devices inherit no app/user privileges.
Two-phase unattended renewal uses locally generated replacements with a 24-hour
bounded preparation and at most ten minutes of activation overlap. Default expiry
is 30 days; clients normally rotate after seven days. Admin revocation/issuance
remain immediate. Renewal-disable/enrollment deadlines bound renewable access.
See secure device setup and recovery for migrations 010–011,
provisioning, API boundaries and optional device-only HTTPS ingress.