No description
  • Go 75%
  • JavaScript 14.5%
  • CSS 4.5%
  • Python 4.2%
  • HTML 0.9%
  • Other 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
jad0s b0295c2a73
All checks were successful
build-and-push / docker (push) Successful in 3m18s
feat(launcher): expose the launcher on app origins
2026-11-21 10:12:06 +01:00
.forgejo/workflows fixup! fixup! feat: fix SMB flock permission checks, add versioned package releases 2026-11-20 12:26:29 +01:00
cmd fix the app launcher logic 2026-11-20 15:58:54 +01:00
deploy/kubernetes fix the app launcher logic 2026-11-20 15:58:54 +01:00
design fix the app launcher logic 2026-11-20 15:58:54 +01:00
docs feat(launcher): expose the launcher on app origins 2026-11-21 10:12:06 +01:00
examples add external device authentication 2026-11-09 18:30:28 +01:00
internal feat(launcher): expose the launcher on app origins 2026-11-21 10:12:06 +01:00
scripts fix the app launcher logic 2026-11-20 15:58:54 +01:00
.dockerignore first deployment checkpoint 2026-11-07 22:25:40 +01:00
.gitignore import trellis 2026-11-03 13:02:37 +01:00
BUILDING-THIN-APPS-v0.4.md feat(launcher): expose the launcher on app origins 2026-11-21 10:12:06 +01:00
compose.blobs.yaml import trellis 2026-11-03 13:02:37 +01:00
compose.dev.yaml import trellis 2026-11-03 13:02:37 +01:00
compose.yaml import trellis 2026-11-03 13:02:37 +01:00
Dockerfile add external device authentication 2026-11-09 18:30:28 +01:00
Dockerfile.dev first deployment checkpoint 2026-11-07 22:25:40 +01:00
go.mod first deployment checkpoint 2026-11-07 22:25:40 +01:00
go.sum first deployment checkpoint 2026-11-07 22:25:40 +01:00
LICENSE Initial commit 2026-10-31 22:09:10 +00:00
Makefile add external device authentication 2026-11-09 18:30:28 +01:00
README.md add external device authentication 2026-11-09 18:30:28 +01:00
TRELLIS-v0.7.md add external device authentication 2026-11-09 18:30:28 +01:00
trellisapp.yaml import trellis 2026-11-03 13:02:37 +01:00

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.