Installation

Installation

Auton8 is a single ASP.NET Core application plus a set of supporting services. Everything except the app itself runs in Docker, and the local stack is session-scoped: you start it once and restart the app as often as you like.

Nothing is seeded. A fresh database has no users, and there is no registration page or setup wizard. You must configure a first administrator before the first start — see First administrator. Earlier versions shipped an admin account whose password hash and salt were committed to the repository; if you are upgrading from one of those, change that password immediately, because it is public.

Prerequisites

Requirement	Why
Docker Desktop (or Docker Engine + Compose v2)	Postgres, Flowable, Redis, NATS, the Dapr control plane and the Node sidecars
.NET 10 SDK	Builds and runs the web application
Node 24	Builds the SPA and runs the two sidecars
Dapr CLI	The app-scoped sidecar; it is deliberately not in Compose, because it starts and stops with the app process

The repository pins Node with .nvmrc and engines.node. Both sidecar images are node:24-alpine.

Quick start

git clone https://github.com/nathanpond/Auton8.git
cd Auton8

# Start Postgres, Flowable, Redis, NATS and the Dapr control plane.
make infra-up

# Choose the first administrator. Without this there is no way to sign in.
export Bootstrap__AdminUsername=admin
export Bootstrap__AdminPassword='pick something'

make app

Then open http://localhost:5108 and sign in with those credentials.

make app ensures the required Compose services are up and ready, then launches the app with its Dapr sidecar. It is the default local start path.

Useful targets

Command	Effect
make infra-up	Start the shared stack
make infra-ensure	Start it only if needed, and wait for readiness
make infra-up-dashboard	Also start the Dapr dashboard on :8081
make infra-down	Stop infrastructure; leaves data in place
make infra-reset	Destroys the bind-mounted data under infra/mounts/
make app / make app-dapr	Run the app with a Dapr sidecar
make infra-logs / make infra-ps	Inspect the stack

What the stack runs

All published ports bind to 127.0.0.1, not 0.0.0.0. The local stack ships known credentials, so exposing it on every interface would put a writable database on whatever network the machine is attached to. Containers reach each other over the Compose network, which is unaffected.

Service	Local address	Purpose
postgres	127.0.0.1:5432	Application database, and Flowable's
flowable	127.0.0.1:8080/flowable-rest	BPMN engine
redis	127.0.0.1:6379	Dapr state and pub/sub
nats	127.0.0.1:4222, monitoring :8222	JetStream — audit events, workflow signals, executor jobs
dapr-placement	127.0.0.1:50006	Dapr actor placement
dapr-scheduler	127.0.0.1:50007	Dapr scheduled jobs
hocuspocus	ws://127.0.0.1:1234	Yjs collaboration sidecar
executor	no port	Sandboxed code runner; serves pipeline-code-run.> over NATS
dapr-dashboard	127.0.0.1:8081	Only under the dashboard profile

See Integrations for what each one is wired to, and External-Services for why each is there.

First administrator

The first account is created by the application at startup, from configuration:

export Bootstrap__AdminUsername=youradmin
export Bootstrap__AdminPassword='a password you choose'

The rules, in full:

• It runs only while local_users is empty. On a database that already has users it does nothing, so leaving the variables set across restarts is harmless — and cannot be used to add a second privileged account to a running install.
• It runs only when both username and password are supplied. If either is missing it creates nothing and logs a warning naming the two settings. There is deliberately no default password.
• The account it creates is granted SuperAdmin directly.

Optional keys:

Key	Default	Notes
Bootstrap__AdminEmail	<username>@localhost
Bootstrap__AdminUserId	random GUID	Pin only if you have a reason to
Bootstrap__GrantSuperAdmin	true	false creates the account without privilege

Configuration binds through the normal providers, so an environment variable, user-secrets, or a mounted secret file all work. Use __ (double underscore) for nesting in environment variables: Bootstrap__AdminPassword.

Running the tests

The backend suite needs three services; the end-to-end suite needs the whole stack.

cd infra && docker compose -p infra up -d postgres nats nats-init redis
cd .. && dotnet test tests/AutoNate.Web.Tests        # ~13 min, 1667 tests

cd src/AutoNate.Spa && npm ci && npm run lint && npx tsc -b && npm run build

The end-to-end suite (tests/AutoNate.E2E.Tests) additionally needs Flowable, the Hocuspocus sidecar, and a built plugins/HelloPlugin/dist/HelloPlugin.zip.

Order matters locally: running the E2E suite empties src/AutoNate.Web/wwwroot and leaves stale static-web-asset manifests, which fails the backend suite on the next run. If that happens, clear the manifest caches and rebuild with -p:BuildSpa=true. CI is unaffected because the jobs are separate.

See Testing for what each suite covers.

Production deployment

The development defaults are tuned for a single machine with the local Compose stack, and several are wrong for anything reachable from outside the host. The full list lives in docs/DEPLOYMENT.md; the essentials:

• AllowedHosts ships "*". Lock it to the hostnames the app actually serves — a wildcard behind a misconfigured proxy enables Host-header injection and cache poisoning.
• ConnectionStrings:Default, Flowable:Username/:Password — rotate away from the dev values.
• WorkflowBehaviors:CallbackSharedSecret must be set, and must match autonate.flowable-events.callback-shared-secret on the Flowable side. The host refuses to start without it outside Development.
• Authorization:Enabled=true, Enforcement=full — the host refuses to start otherwise. Leave Authorization:AssignSuperAdminToAllExistingUsers false: enabling it grants SuperAdmin to every existing user the first time it runs. It is a migration aid for deployments predating role assignments, not first-run setup.
• Data__Root — the runtime data tree (uploads, plugins, public /files assets, per-plugin scratch). Mount writeable persistent storage here. Note this is Data__Root, not AUTONATE_DATA_ROOT, which does not exist.
• TLS is not terminated by the app. Front it with a reverse proxy that forwards X-Forwarded-For / X-Forwarded-Proto. The agent SSE streams (/api/agent/...) and the Bus Watcher hold long-lived connections — disable buffering and allow a generous read timeout (≥10 minutes) on those routes.

Troubleshooting

"Nobody can sign in." local_users is empty and no bootstrap credentials were configured. The startup log says so explicitly. Set the two variables and restart.

The app refuses to start, complaining about Dapr. In Development it fails fast when no sidecar is reachable. Use make app-dapr, or set AUTONATE_ALLOW_RUNNING_WITHOUT_DAPR=true when you deliberately want to run without event-driven features.

Editor pages log ERR_CONNECTION_REFUSED on ws://localhost:1234. The Hocuspocus sidecar is not running. Notes and Documents need it for collaborative editing.

A 504 "Outdated Optimize Dep" after installing large npm packages. rm -rf .vite/deps && npm run dev -- --force.