Quick start

ALIAS is one server program, alias-support, with one configuration file. For anything beyond a trial, add a Postgres database.

Try it in a minute

With no database configured, everything is kept in memory and is gone when the server stops. That's fine for a first look.

# alias.toml
listen = "127.0.0.1:8080"

[admin]
instance_role = "alias.admin"

[[product]]
id = "demo"
name = "Demo"
contact = "optional"
contact_kinds = ["email", "other"]
fields = [{ name = "level", label = "Level", type = "text" }]
keys = [{ name = "default", env = "DEMO_KEY" }]

DEMO_KEY=demo-key-at-least-16-chars ALIAS_DEV_ADMIN_TOKEN=try ./alias-support -config alias.toml

Open http://127.0.0.1:8080/admin/?token=try for the admin page, and point a client at http://127.0.0.1:8080 with the key demo-key-at-least-16-chars.

WARNING

ALIAS_DEV_ADMIN_TOKEN lets anyone holding that token in as the instance's administrator, with no sign-in. Use it only on your own machine.

Running it for real

ALIAS_DATABASE_URL=postgres://alias:…@db/alias ALIAS_DEMO_KEY=… ./alias-support -config alias.toml

The schema is created and migrated on start. Secrets never go in the file: the database's URL and every key come from the environment variable, or the file, that the configuration names.

The configuration file

Setting
listen	the address to serve on (:8080)
database_env	the environment variable that holds the Postgres URL. Leave it out to keep everything in memory
trust_proxy	take the client's address from X-Forwarded-For. Only behind a proxy that sets it; the limits per address use it
[admin] issuer, client_id	the OpenID Connect provider for the admin page, and its public client
[admin] agents	confidential clients allowed in with client credentials (tools, bots)
[admin] instance_role	the role that manages the instance: products, keys, every product's desk

Each [[product]] has:

Setting
id, name	its id (lower case, in keys and addresses) and its name
privacy_url	its privacy policy, shown to clients
admin_role	the role whose holders work its desk
contact, contact_kinds	off or optional; email, other
keep_done_days, keep_unseen_days	how long a resolved report is kept, and an id nobody has used
origins	the browser origins allowed to use its keys
fields	the context a report may carry: text, number, bool, geo, link (with a template such as "https://example.com/level/{level}"), json
telemetry_max	the telemetry's size in bytes (32 KB by default, 256 B to 1 MB)
telemetry_schema, telemetry_schema_file	a JSON Schema (2020-12, no remote $ref) the telemetry must match
branding	logo, colour, accent
limits	per hour: reports_per_user, reports_per_ip, comments_per_user, reads_per_user
keys	{ name, env } or { name, file }: where each key's value comes from (at least 16 characters). Only its hash is stored

Products in the file are read-only on the admin page, and the file always wins. A product the file stops listing becomes the admin page's, so its users and reports aren't lost. A key revoked on the page stays revoked across restarts, even one from the file.

Products made on the admin page live in the database. Their keys are issued there, and each is shown once.

Roles

Who	May
a product's admin_role	that product's desk: tickets, answers, users (block, reset, erase), revoking a key, the log
instance_role	everything: creating, editing and deleting products (not the file's), issuing and restoring keys, every product's desk, the instance's log

Addresses

• Users (your product's clients): /v1/… with the product's key, plus the user's id and secret. See the API reference.
• Support: the admin page at /admin/, and its API under /v1/admin/… with a bearer token.
• Health: /healthz, /readyz (the database answers), /version.

Several replicas

An answer is pushed over the user's open stream by the replica that took it. With several replicas, a stream on another one misses it until the client next polls. The clients poll when they reconnect, and every minute by default. A single replica needs nothing more.