go-doc/data/docs/go-tell.md

<!-- go-doc:generated:begin source=go-tell signature=911c111a08c2bfd4f631756f16920125 generated=2026-10-07 08:28 UTC -->
# go-tell

Go Tell is a small content CMS: one Go binary that serves the API and embeds the React frontend, backed by a JSON file. It is served from a single host, `https://tell.dev`, and it uses [Go Loose](https://github.com/danyel/go-loose) to decide who is allowed to edit.

|  |  |
| --- | --- |
| Module | github.com/danyel/go-tell · go 1.27.1 · 13 Go files |
| Endpoints | 14 endpoints |
| Components | 3 component directories |
| Tests | 26 in 5 files |
| Go lines | 3050 lines |

> Everything between the generated markers is rewritten by every sync. Notes written outside the markers are kept.

## For Users

### What this application does

Go Tell is a small content CMS: one Go binary that serves the API and embeds the React frontend, backed by a JSON file. It is served from a single host, `https://tell.dev`, and it uses [Go Loose](https://github.com/danyel/go-loose) to decide who is allowed to edit.

The project ships its own README at `README.md`, which is the long form of this page. The three audience tabs split the same facts three ways so you only read the part that concerns you.

### Reading this in go-doc

Open the page and pick the tab that matches you:

- **User** — you use the finished application. This section is all you need.
- **Operator** — you run it. Configuration, ports and deployment notes are under that tab.
- **Developer** — you integrate with it or change it. The API and layout tables are under that tab.

The feedback panel stores a note per audience, tagged with your badge, so operators and developers can see which audience raised it.

### Where the original documentation lives

This project already carries 4 Markdown documents. They stay in the project repository: this page points at them instead of copying them, so there is always exactly one copy of the truth.

| Document | Size |
| --- | --- |
| `README.md` | 7238 bytes |
| `deploy/helm/go-tell/README.md` | 9194 bytes |
| `ui/app/README.md` | 1266 bytes |
| `ui/changelog.md` | 5324 bytes |

---

## For Operators

### Running it locally

This project has no root Makefile, so the binary or container is run directly.

### Image

`Dockerfile` builds from `node:22-alpine`, `golang:1.27-alpine`, `alpine:3.20` in stages: ui, backend and exposes 8080.

### Configuration

Every environment variable found in the source or in a `.env` file:

| Variable | Example | Found in |
| --- | --- | --- |
| `CMS_ALLOWED_ORIGINS` | `http://localhost:5173` | .env file |
| `CMS_CONTENT_FILE` | — | .env file |
| `CMS_HTTP_ADDR` | `:8080` | .env file |
| `CMS_POSTGRES_URL` | — | .env file |
| `CMS_PROFILE` | `demo` | .env file |
| `CMS_SSO_COOKIE` | — | .env file |
| `CMS_SSO_HEADER` | `X-SSO-Token` | .env file |
| `CMS_SSO_TOKEN` | — | .env file |
| `GO_LOOSE_APP_DOMAIN` | `tell.dev` | .env file |
| `GO_LOOSE_AUTH_DOMAIN` | `auth.dev` | .env file |
| `GO_LOOSE_CA_FILE` | — | .env file |
| `GO_LOOSE_CLIENT_ID` | — | .env file |
| `GO_LOOSE_CLIENT_SECRET` | — | .env file |
| `GO_LOOSE_TENANT` | `tell` | .env file |
| `VITE_API_BASE_URL` | — | .env file |
| `VITE_CONTENT_ENDPOINT` | `/api/content` | .env file |
| `VITE_SESSION_ENDPOINT` | `/api/auth/session` | .env file |
| `VITE_SSO_LOGIN_URL` | — | .env file |

### Network surface

Ports referenced across the project: `8080`.

### Deployment artefacts

Helm 1 chart found:

- `deploy/helm/go-tell`

### Operations documentation that already exists

Read these in place rather than duplicating them here:

- `deploy/helm/go-tell/README.md` — Go Tell Helm chart

---

## For Developers

### Module layout

- go.mod — module github.com/danyel/go-tell, go 1.27.1, 13 direct and 58 indirect dependencies

### HTTP API

Every route registration found in the source:

| Method | Path | Handler |
| --- | --- | --- |
| ANY | `/` | `singlePageApp` |
| ANY | `/api/admin/reset` | `adminReset` |
| ANY | `/api/auth/session` | `session` |
| ANY | `/api/auth/sudo` | `sudo` |
| ANY | `/api/auth/users` | `users` |
| ANY | `/api/content` | `contentCollection` |
| ANY | `/api/content/` | `contentDetail` |
| ANY | `/api/content/badges` | `contentBadges` |
| ANY | `/api/content/categories` | `contentCategories` |
| ANY | `/api/content/clear` | `adminReset` |
| ANY | `/api/dev/null` | `contentCollection` |
| ANY | `/api/dev/null/` | `contentDetail` |
| ANY | `/api/protected` | — |
| ANY | `/health` | `func` |

### Direct dependencies

- `github.com/danyel/go-loose` v0.0.0-20261002224534-b011701522b1
- `github.com/go-chi/chi/v5` v5.2.3
- `github.com/golang-jwt/jwt/v5` v5.3.0
- `github.com/google/uuid` v1.6.0
- `github.com/jackc/pgx/v5` v5.11.0
- `github.com/ledongthuc/pdf` v0.0.0-20260907135840-6c8c28e0e8a0
- `github.com/pressly/goose/v3` v3.26.0
- `github.com/rabbitmq/amqp091-go` v1.15.0
- `github.com/testcontainers/testcontainers-go` v0.44.0
- `github.com/testcontainers/testcontainers-go/modules/postgres` v0.44.0
- `golang.org/x/crypto` v0.54.0
- `gorm.io/driver/postgres` v1.6.0
- `gorm.io/gorm` v1.31.0

### Directory map

| Directory | Files | Lines | Likely purpose |
| --- | --- | --- | --- |
| `ui/` | 26 | 1636 | frontend assets |
| `deploy/` | 20 | 81 | deployment manifests |
| `internal/` | 12 | 2988 | unimportable application internals |
| `cmd/` | 1 | 62 | binary entry points |
| `migrations/` | 1 | 9 | schema migrations |

### Languages

- **YAML** — 20 files, 14872 lines
- **Go** — 13 files, 3050 lines
- **JSON** — 5 files, 2025 lines
- **TypeScript** — 15 files, 1616 lines
- **Markdown** — 4 files, 499 lines
- **CSS** — 1 file, 383 lines
- **Templates** — 1 file, 76 lines
- **txt** — 1 file, 35 lines
- **HTML** — 1 file, 29 lines
- **SQL** — 1 file, 9 lines
<!-- go-doc:generated:end -->

---

## Related Documentation

- [go-doc](go-doc.md) — The documentation platform itself
- [go-loose](go-loose.md) — Auth middleware (used for SSO)