No description
  • Python 97.3%
  • HTML 2.1%
  • Dockerfile 0.4%
  • Mako 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Johan Wassberg ee44971d34
All checks were successful
test-and-publish / test (push) Successful in 2m7s
test-and-publish / publish (push) Successful in 50s
Expose GNA_API_URL as api_url in GET /server
2026-11-22 13:16:13 +01:00
.forgejo/workflows Dockeru 2026-11-15 14:45:31 +01:00
pages.example Explain the name 2026-11-22 13:10:29 +01:00
src/gna Expose GNA_API_URL as api_url in GET /server 2026-11-22 13:16:13 +01:00
tests Expose GNA_API_URL as api_url in GET /server 2026-11-22 13:16:13 +01:00
.dockerignore Dockeru 2026-11-15 14:45:31 +01:00
.env.example Serve data through an additional domain 2026-11-22 13:06:15 +01:00
.gitignore Intitial commit 2026-10-24 13:49:22 +02:00
docker-compose.yml Dockeru 2026-11-15 14:45:31 +01:00
Dockerfile Dockeru 2026-11-15 14:45:31 +01:00
gna-design.md Intitial commit 2026-10-24 13:49:22 +02:00
pyproject.toml Serve documentation 2026-11-21 18:58:25 +01:00
README.md Explain the name 2026-11-22 13:10:29 +01:00
uv.lock Serve documentation 2026-11-21 18:58:25 +01:00

Gná server

Self-hosted messaging hub for talking to bots and automated systems. See gna-design.md for the design.

The name: in Norse mythology Gná is the goddess who runs Frigg's errands, riding her horse Hófvarpnir through the air and over the sea to carry messages between the worlds. Gná (say "gnah", with the g) carries messages between you and your machines. Technical names use gna, without the accent: the package, the CLI, the domain.

Running

uv sync
cp .env.example .env          # then edit
uv run gna db upgrade
uv run gna serve              # binds 127.0.0.1:8000; put Caddy/nginx with HTTPS in front

Run a single process: long-poll wake-ups and presence are in memory. The server refuses to start if the database schema is not at the latest migration.

gna serve also reads its options from GNA_HOST, GNA_PORT and GNA_FORWARDED_ALLOW_IPS.

With Docker

Every push to main that passes the tests publishes code.smolnet.org/theseal/gna-server:latest (and :<short sha>); a tag v1.2.3 publishes :v1.2.3 without moving :latest (.forgejo/workflows/container.yaml, which needs the CI_RUNNER secret).

On the host, next to docker-compose.yml:

  • .env from .env.example. The compose file fixes the paths inside the container (database and files in the gna-data volume, pages, APNs key) and trusts the proxy's X-Forwarded-For, so .env needs no paths.
  • pages/ from pages.example/, filled in.
  • AuthKey.p8, the APNs key, readable only by the container's user (uid 10001): sudo chown 10001 AuthKey.p8 && sudo chmod 600 AuthKey.p8.

Then docker compose up -d: the container migrates the database and starts, listening on 127.0.0.1:8000 for the reverse proxy that terminates HTTPS. Run exactly one instance. Admin commands run inside it, e.g. docker compose exec gna gna invite --name "Johan".

Passkeys and universal links need a real domain with valid HTTPS (GNA_PUBLIC_URL). To point bots at another name for the same server (say api.gna.example.com), set GNA_API_URL: the integration guide's examples then use it, while everything else stays on GNA_PUBLIC_URL.

A server the App Store build talks to needs a privacy policy and a support page. Copy pages.example/ outside the repository, fill in every [[…]], and set GNA_PAGES_DIR to it: privacy.html and support.html are then served at /privacy and /support (read on each request, so edits need no restart; 404 while unset). The app links to both.

On a server that people you don't know can use, set GNA_ALLOW_INTERNAL_URLS=false. Otherwise anyone can create a conversation that allows internal URLs and have the server fetch addresses on its own network. With it off, such conversations are rejected (400 internal_urls_disabled), ones stored earlier are treated as off, and the app hides the setting.

Demo

With GNA_DEMO_ENABLED=true (which requires GNA_ALLOW_INTERNAL_URLS=false) the app offers Try the demo: POST /auth/demo creates a temporary account with no passkey, holding a Quotes conversation whose bot answers with public-domain quotes, sends quote cards, and offers a reminder that arrives as a notification with Yes/No buttons. The visitor can create up to GNA_DEMO_MAX_CONVERSATIONS conversations of their own and tokens for them, so the curl example works too.

Images sent into a demo from outside (app uploads, bot uploads, image_url) are validated as usual, then discarded: only a grey placeholder of the same shape is stored, so an open demo never hosts strangers' pictures. The quote bot's own cards are real.

The bot is an ordinary integration running inside the server (its token is the demo account's first one): it long-polls and sends through the same code as any bot. After a restart, bots of unexpired demos resume from the current position; what was written meanwhile goes unanswered. The pruner deletes demo accounts with everything they own after GNA_DEMO_TTL_HOURS.

Limits, all in memory (one process): GNA_DEMO_PER_IP_PER_HOUR new demos per client address (behind a proxy, gna serve --forwarded-allow-ips must name it so the real address is seen), GNA_DEMO_MAX_ACCOUNTS at once, and GNA_DEMO_MESSAGES_PER_HOUR messages from integrations (the quote bot's included) into one demo account.

The server relays, the apps keep

Messages are not archived. Once a minute the server deletes, with their images:

  • messages that every app session active in the last 7 days, and every bot listening in the conversation, has fetched, 10 minutes after that (GNA_DELIVERED_RETENTION_SECONDS);
  • anything older than 7 days, delivered or not (GNA_UNDELIVERED_MAX_AGE_HOURS);
  • uploads never used in a message, after an hour.

Fetching is confirmed by the long-poll itself: asking for what follows after confirms everything up to it. A message with callback buttons stays until pressed (or 7 days), since presses go through the server. A reply to a deleted message keeps a snapshot of its quote; a reply to a message the server no longer has carries only its ID. GET /messages with a token therefore returns only what has not been delivered yet. History lives in the app.

Admin CLI

gna invite --name "Johan"                   # single-use, expiring account invite link
gna invites                                 # open / used / expired / revoked
gna invite revoke inv_…
gna passkey-link --user johan               # add a passkey / recover an existing account
gna accounts [--demo]                       # all accounts, or demos that have not expired
gna account delete --user johan             # with everything it owns [--yes]; ends a demo too
gna conversation create --user johan --name Garage [--allow-internal-urls]
gna conversations --user johan
gna conversation delete --user johan --conversation conv_…   # with its messages and tokens
gna token create --user johan --conversation conv_… --name "garage script" [--send-only]
gna tokens --user johan --conversation conv_…
gna token revoke --user johan --conversation conv_… tok_…
gna token revoke-all --user johan --conversation conv_…

--user takes an account ID or a display name (case-insensitive; must be unambiguous).

IDs that people read are pronounceable: a type prefix and two proquints, e.g. acc_lusab-babad or conv_gutih-tugad (32 random bits; a new one is checked against existing rows and drawn again if taken). They are not secrets: every lookup also checks the owner. Older hex IDs stay valid. Sessions and passkey ceremonies, which nobody reads, keep long random IDs.

Integrations

Bots and scripts authenticate with a conversation's token (Authorization: Bearer gna_…), send with POST /messages and long-poll GET /updates for replies and button presses:

curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Front door is unlocked. Lock?",
       "buttons": [[{"label": "Lock", "data": "lock"}, {"label": "Ignore", "data": "ignore"}]]}' \
  https://gna.example.com/messages

Everything else (images, buttons in notifications, receiving, errors, limits, a complete bot) is in the guide, src/gna/docs/integrations.md. Every server also serves it at /integrations, with its own address in the examples; the app links there from its token screens. The OpenAPI spec is at /openapi.json (interactive docs at /docs).

API overview

Endpoint Who Purpose
POST /auth/invite anyone Look up an invite/passkey link (name to greet with)
POST /auth/register/options, /verify anyone Passkey registration from a link
POST /auth/login/options, /verify anyone Passkey login (discoverable credentials)
POST /auth/dev/login anyone Only with DEV_AUTH=1
POST /auth/logout, GET/PATCH /me app / token Session and account
DELETE /me app Delete the account: conversations, messages, tokens, passkeys, sessions
GET /server anyone What this server permits (allow_internal_urls, demo_enabled)
POST /auth/demo anyone Start a demo account (when enabled; 429 when over a limit)
GET/POST /conversations, GET/PATCH /conversations/{id} app Conversations, mute (muted_until)
DELETE /conversations/{id} app Delete with messages and tokens (bots get 401)
POST /conversations/{id}/read app Read marker (unread counts)
GET/POST/DELETE /conversations/{id}/tokens app Integration tokens (DELETE revokes all)
DELETE /conversations/{id}/tokens/{token_id} app Revoke one token
POST /conversations/{id}/messages app Send as the user (reply_to, …)
POST /conversations/{id}/messages/{mid}/press app Press a callback button (409 once used)
GET /messages?after=&conversation=&timeout= app / read token The single stream: message and message_updated events
POST /messages token Send (JSON or multipart with image)
GET /updates?after=&timeout= read token User messages and callback events
POST /attachments, GET /attachments/{id}[/thumb] app / token Images
POST /devices, DELETE /devices/{token} app APNs device registration
GET /.well-known/apple-app-site-association anyone Associated domains
GET /integrations anyone The integration guide as a web page

Errors are {"error": "<code>", "detail": …}.

Notification categories for the app

The app registers these iOS categories. Action i presses button (row 0, col i).

notification_buttons Category Actions
(none) gna.message Reply (text input)
ok gna.ok OK
yes_no gna.yes_no Yes, No
ok_cancel gna.ok_cancel OK, Cancel

Push payloads carry message_id, conversation_id and, for images, attachment_url (a thumbnail) for the notification service extension.

With DEV_AUTH=1 (and no GNA_PUSH_BACKEND set) each notification is printed to stdout instead, once per notification and without needing a registered device. Mute and the "app is connected" check still apply, so a notification only prints when a real push would be sent.

Development

uv run pytest
uv run ruff check src tests && uv run black --check src tests && uv run isort --check src tests

After changing src/gna/store/sql/models.py, generate a migration against an up-to-date database and review it:

uv run gna db upgrade && uv run gna db revision -m "add foo"

tests/test_infra.py::test_migrations_match_models fails if models and migrations diverge.