Quick start: running ALIAS yourself

This page is for hosting ALIAS on your own machines. On the hosted service there's nothing to install: see Pricing.

ALIAS is one server program, alias-support, with one configuration file. It comes with the Self-hosted licence: the binaries, the image ghcr.io/emdzej/alias-support, the Helm chart and the install scripts. There's no separate demo build: the program you try is the one you deploy. The clients and tools your product uses are free, on alias-releases. For anything beyond a trial, add a Postgres database.

A first look on your own machine

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" }]

ALIAS_DEV_ADMIN_TOKEN=try ./alias-support -config alias.toml

Open http://127.0.0.1:8080/desk/?token=try for the panel, issue a key for Demo there (it's shown once), and point a client at http://127.0.0.1:8080 with that key.

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-support -config alias.toml

The schema is created and migrated on start. Secrets never go in the file: the database's URL comes from the environment, and every product's keys are issued on the panel. Every setting but the products can also come from the environment, and the file itself is optional: see Deploying.

The configuration file

Setting
listen	the address to serve on (:8080)
database_env	the environment variable that holds the Postgres URL (ALIAS_DATABASE_URL if left out). With no URL, everything is kept 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
public_url	where browsers reach it: the sign-in returns to /auth/callback there
[admin] issuer, client_id	the OpenID Connect provider for the panel, and its client. Its access tokens need the client id in aud, and the people's roles in roles or groups (or preset = "keycloak")
[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
redact	rules for the telemetry, context and note: { path, strategy, … }, applied by the clients before anything leaves the device and by the server again. See redaction
removable	telemetry or context paths the user may take out before sending
attachments	max files per report (5), their bytes together (10 MB), and their types

Products in the file are read-only on the panel, and the file always wins. A product the file stops listing becomes the panel's, so its users and reports aren't lost.

Products made on the panel live in the database.

Every product's keys are issued on the panel, a product from the file's too. A product can have as many as it needs, each with its own name (web, steam, ios), shown once, and revoked on its own. Only a hash of each is stored.

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): /api/v1/… with the product's key, plus the user's id and secret. See the API reference.
• Support: the panel at /desk/, which sends you straight to your provider to sign in, and its API under /api/v1/admin/… (with a bearer token, for scripts).
• 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.