Getting Started

Getting Started

Running Elsa with a working designer UI, from nothing.

Prerequisites

• Docker 20.10 or later
• A free port 8080

Nothing else. No .NET SDK, no database.

---

1. Run it

The combined image is the shortest path — API and Studio in one container, one origin, no CORS to configure.

docker run -d --name elsa-pro -p 8080:8080 \
  -e CShells__Shells__Default__Features__DefaultAdminUser__AdminUsername=admin \
  -e CShells__Shells__Default__Features__DefaultAdminUser__AdminPassword='ChangeThisPassword123!' \
  -e CShells__Shells__Default__Features__Identity__SigningKey="$(openssl rand -base64 32)" \
  ghcr.io/valence-works/runtime-ce-combined:latest

On Windows PowerShell:

docker run -d --name elsa-pro -p 8080:8080 `
  -e CShells__Shells__Default__Features__DefaultAdminUser__AdminUsername=admin `
  -e CShells__Shells__Default__Features__DefaultAdminUser__AdminPassword='ChangeThisPassword123!' `
  -e "CShells__Shells__Default__Features__Identity__SigningKey=$([Convert]::ToBase64String((1..32|%{Get-Random -Max 256})))" `
  ghcr.io/valence-works/runtime-ce-combined:latest

What those three settings are

Setting	Why it's here
…DefaultAdminUser__AdminUsername	The admin account provisioned on first start. Defaults to admin.
…DefaultAdminUser__AdminPassword	Defaults to password. Always override.
…Identity__SigningKey	Signs authentication tokens. Ships as a placeholder. Anyone who knows it can mint valid tokens for your instance, so generate a real one (256-bit minimum).

Those long key names are CShells configuration paths — CShells:Shells:Default:Features:… — flattened into environment variables with __ as the separator. Default is the shell name. Configuration explains the shape.

⚠️ Shells is keyed by shell name, not by index. The segment is Default. Using 0 there creates a different shell called 0, and your admin user will silently not appear where you expect it.

2. Open Studio

http://localhost:8080 — sign in with the username and password you set.

What	URL
Studio UI	http://localhost:8080
Elsa API	http://localhost:8080/elsa/api
Health (readiness)	http://localhost:8080/health
Liveness	http://localhost:8080/alive

Check it's healthy:

curl -f http://localhost:8080/health

If the page doesn't load, docker logs elsa-pro first — then Troubleshooting.

3. Build a workflow

In Studio: Workflows → New workflow, drag activities onto the canvas, publish. Add an HTTP Endpoint trigger to invoke a workflow over HTTP.

Workflow authoring is the same as open source Elsa, so the Elsa Workflows documentation applies in full. This wiki covers the packaging — pulling, running, configuring. It does not duplicate the engine docs.

---

⚠️ Before you use this for anything real

The command above is a demo, not a deployment. Three things are wrong with it:

1. Data is in SQLite inside the container. Remove the container, lose everything. → Persistence and Databases
2. The password is on the command line, which puts it in your shell history and in docker inspect. → use a mounted config file, see Configuration
3. No TLS, no CORS restrictions, no resource limits. → Production Checklist

---

Next steps

• Separate server and Studio containers → Choosing an Image
• Docker Compose with a real database → Running the Images
• Add PostgreSQL, RabbitMQ, Quartz → Extending with Nuplane
• Move config out of -e flags → Configuration