Installation

Installation

There are two ways to run Auton8, and which one is yours depends on what you want to do with it.

	Run a release	Develop from source
You want to	use Auton8	change Auton8
Prerequisites	Docker	Docker, .NET 10 SDK, Node 24, Dapr CLI
Start	download two files, docker compose up -d	clone, make preflight, make app

Auton8 1.0 requires a fresh database. Upgrading a 0.x install is not supported — 0.x moved fast and made no compatibility promise. Releases after 1.0 will carry upgrade paths; the schema ledger that makes them possible ships in 1.0 for that reason.

Nothing is seeded. A fresh database has no users and there is no registration page or setup wizard. You configure a first administrator before the first start, either way — 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.

---

Run a release

Docker is the only prerequisite. No clone, no build, no toolchain.

1. From the latest release, download compose.yml and env.template into an empty directory and rename the second one to .env.

2. Fill in .env. Two things are required and neither has a default — a first administrator, and three secrets you generate yourself:

echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)"
echo "WORKFLOW_CALLBACK_SECRET=$(openssl rand -hex 32)"
echo "YJS_SHARED_SECRET=$(openssl rand -hex 32)"

Nothing generates these for you. Software that mints its own credentials is how a placeholder becomes a live secret.

3. Start it:

docker compose up -d

First start pulls the images and initialises the database; a few minutes is normal. Then open http://localhost:5108 and sign in with the credentials from step 2.

Verifying what you downloaded

Every image is pinned by digest, and each carries a signed provenance attestation tying it to the commit and workflow that built it:

gh attestation verify \
  oci://ghcr.io/nathanpond/auton8/autonate-web@<digest from compose.yml> \
  --repo nathanpond/Auton8

Before anyone else can reach it

The released stack terminates no TLS and its services trust each other on the compose network. APP_ENVIRONMENT=Development also keeps a permissive AllowedHosts and relaxes startup checks that exist for good reasons.

For anything beyond a laptop, set APP_ENVIRONMENT=Production and ALLOWED_HOSTS to the hostnames you serve, and put a reverse proxy in front that handles HTTPS. See Production deployment.

---

Develop from source

Prerequisites

The authoritative list, with the minimum version of each and how to install it, is infra/prerequisites — one file, rather than a version restated here, in the Makefile and in the script, which is how three copies come to disagree.

make preflight checks all of them plus port availability, and reports everything wrong in one pass so a machine is fixed once rather than once per missing tool. make infra-up, make infra-ensure and make app all run it first, so you do not have to remember it.

Quick start

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

make preflight        # optional: infra-up runs it anyway
make infra-up         # Postgres, Flowable, Redis, NATS, the Dapr control plane

export Bootstrap__AdminUsername=admin
export Bootstrap__AdminPassword='pick something'

make app

Then open http://localhost:5108.

make app runs the application on the host with its own Dapr sidecar. That is the development inner loop: fast rebuilds and a debugger that can attach to the process.

Running everything in containers

If you would rather not install the .NET SDK, Node and the Dapr CLI, the whole product runs as containers from the source tree too:

cp .env.example .env      # then set Bootstrap__AdminUsername / AdminPassword
make app-container        # the app and its Dapr sidecar, plus the stack
make app-container-down   # stops only the app containers

This uses the app compose profile, which is off by default so the ordinary make app loop is unaffected.

Useful targets

Command	Effect
make preflight	Check prerequisites and ports
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 app / make app-dapr	Run the app on the host with a Dapr sidecar
make app-container	Run the app as a container instead
make lockfiles	Regenerate packages.lock.json after changing a dependency
make infra-down	Stop infrastructure; leaves data in place
make infra-reset	Destroys the bind-mounted data under infra/mounts/

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.