Alex Architect / Deployment

for whoever deploys it

Deployment

Alex Architect is a single Node process that speaks plain HTTP and stores JSON on a volume. It starts no database of its own. Everything below assumes you have the repository checked out.

This page is a map, not a manual. The full guides live in the repository as Markdown, next to the code they describe, so they change when the code does. Each link below goes to the real file.

PKlocalRun it locally

One command. No database to install, no account to create.

docker compose up --build -d

# http://localhost:8080 — sign in as admin / admin, then change the password

docker compose down keeps your data in the named volume; down -v destroys it.

Connecting to a database on the same machine? Inside the container 127.0.0.1 is the container. Use host.docker.internal instead.

PKcompanyDeploy for a company

There is no published image yet, so both paths build from source. Kubernetes is two commands.

# builds the image, pushes it, and writes a Kustomize overlay wired to your host
./scripts/aa-deploy-k8s.sh --host er.example.com --registry registry.example.com

kubectl apply -k deploy/k8s/overlays/company

The script also generates a bootstrap administrator password and an AA_CONNECTION_KEY into a git-ignored secret.env. The password is printed once. Run it with --help for the flags: ingress class, TLS secret name, storage size, a second environment.

On a single VM, use the production Compose override behind your own reverse proxy — it binds to loopback only. Example Caddy and nginx configs are in deploy/examples/.

FKdomainYour own domain

Nothing special is needed in the product. It is built for this.

WhereWhat to set
DNSAn A or AAAA record for your host, pointing at the ingress or reverse proxy.
TLSTerminated at the proxy or ingress. The application itself speaks plain HTTP on 8080 and holds no certificates.
ApplicationAA_PUBLIC_URL=https://er.example.com and AA_COOKIE_SECURE=true.
KubernetesIngress host and tls.secretName in the overlay — the deploy script fills both from --host.
AA_PUBLIC_URL is not cosmetic. It is the origin handed to identity providers as the address to return to. If it disagrees with what the browser shows, sign-in lands back on the login screen with no session and no error message. It is the most common and least obvious way a move to a new domain goes wrong.

AA_COOKIE_SECURE is deliberately not inferred from the URL: the application does not quietly decide that your cookies should become Secure.

FKssoSingle sign-on

Google, Microsoft Entra ID, or any standards-compliant OIDC provider. The redirect URI the application sends is {AA_PUBLIC_URL}/api/auth/<provider>/callback — no trailing slash, and the path includes /api.

Two things that cost people an afternoon with Entra ID. The issuer must end in /v2.0 — the v1.0 endpoint publishes a different discovery document and fails validation. And Entra frequently leaves the email claim empty, putting the address in preferred_username instead; if sign-in fails complaining about a missing email, set AA_OIDC_EMAIL_CLAIM=preferred_username.

On a fresh instance the first person to sign in becomes the instance administrator. Worth knowing before you point a whole tenant at it.

NbackupsBackups and the encryption key

Everything lives on one volume: projects, users, saved connections and the key that seals connection passwords.

PathContents
projects/The diagrams themselves, one JSON file each.
auth/auth.jsonUsers, sessions, memberships, access requests.
connections/Saved connections. Passwords sealed with AES-256-GCM.
secrets/connection.keyThe sealing key, generated here unless you set AA_CONNECTION_KEY.
Back the key up separately from the data. Lose it and every stored database password becomes unrecoverable — the projects survive, the credentials do not.

NlimitsLimits worth knowing before you commit

  • oneRun a single API replica. Presence and locks are held in memory and the data volume is single-writer. Do not scale the deployment, and do not use --scale app=2.
  • offMigration Apply is disabled server-side. Diff produces SQL for a human to read and run elsewhere. This is a deliberate decision, not a missing feature.
  • noneNo SMTP. Invitations are copy-a-link. There is nothing to configure and nothing that will silently fail to send.
  • okNo telemetry. Outbound traffic goes only to endpoints you configured: your database, your identity provider, your AI provider if you enabled one.

PKreferenceFull reference in the repository

These are the authoritative documents. They sit beside the code and change with it.

  • Company self-host: VM and Kubernetes

    Quick start, environment checklist for HTTPS, Compose behind a reverse proxy, the Kustomize layout, and what collaboration on one instance does and does not support. Also available in Russian.

    documentation/company-selfhost.md
  • Single sign-on setup

    Google, Microsoft Entra ID and generic OIDC, with the redirect URIs, the required scopes, and a symptom-to-cause table for when sign-in silently returns to the login screen.

    documentation/sso-setup.md
  • Backups and credential recovery

    What to back up, why the encryption key goes somewhere else, and what is recoverable if you lose one of the two.

    documentation/credential-backup.md
  • Administrator password recovery

    The break-glass procedure for when nobody can sign in as an administrator any more.

    documentation/admin-password-recovery.md
  • Support matrix

    Which databases are first-class, which are experimental, and what "experimental" means in terms of what is actually tested.

    documentation/support-matrix.md
  • Security policy

    How to report a vulnerability, what is in scope, what is intended behaviour, and where the operator's responsibility begins.

    SECURITY.md