ElsaWorkflow/CLAUDE.md

CLAUDE.md — Elsa custom server

Notes for future sessions working on this repo. Everything here is the result of "we tried it, this is what actually worked". Read before touching versions, authentication, or the Docker/Coolify wiring.

What this repo is

Custom Elsa Workflows server + Studio, built as one .NET 9 container:

• src/Elsa.CustomServer/ — ASP.NET Core host. Runs the Elsa server API and serves the Studio WASM shell from the same origin. Custom activities live in Activities/ and are auto-registered by AddActivitiesFrom<Program>().
• src/Elsa.Studio.Wasm/ — Blazor WebAssembly Studio shell. Referenced as a project so dotnet publish copies its wwwroot/ into the server's output.
• Dockerfile — multi-stage .NET 9 build. Restores BOTH csprojs before copying sources so the WASM restore lands in cache too.
• Deployed to Coolify as an elsa app at https://elsa.tes.gd, UUID u3qd22pn77pxyx4yf1p5ws2i, build_pack=dockerfile, sourced from gitea.tes.gd/admin/ElsaWorkflow.

Adding a new activity (the whole flow)

1. Drop a .cs under src/Elsa.CustomServer/Activities/, inheriting from CodeActivity, CodeActivity<T>, or Activity (the last for triggerable ones). Decorate with [Activity("Category", "Name", "Description", Kind = ActivityKind.Task)].
2. git push.
3. Fire a Coolify deploy — fire-and-forget, per global rules: curl -sS -X POST "$COOLIFY_URL/api/v1/deploy?uuid=$APP" -H "Authorization: Bearer $COOLIFY_KEY"
4. Hard-refresh the browser (or open incognito — Blazor caches assets aggressively).
5. New activity appears in the Studio toolbox under its declared category.

No AddActivity<T>() needed — the assembly scan picks it up.

Elsa 3.x package version pinning — the tricky part

Server packages and Studio packages have diverged release trains:

• Server: Elsa, Elsa.Http, Elsa.Identity, Elsa.EntityFrameworkCore*, Elsa.CSharp, Elsa.JavaScript, Elsa.Liquid, Elsa.Scheduling, Elsa.Workflows.Api — top out at 3.5.3 on nuget.org.
• Studio: Elsa.Studio* — at 3.7.0.

Do NOT try to force everything to a single version — you'll get "package not found". The 3.7 Studio talks to a 3.5 server just fine (protocol is backward-compatible within v3).

Transitive Microsoft.AspNetCore.Components pins: Studio 3.7 pulls Elsa.Api.Client 3.7.0-rc1 → Microsoft.Extensions.Http.Polly 9.0.13, which requires Microsoft.AspNetCore.Components >= 9.0.13. Pin those explicitly in the WASM csproj or NuGet errors out on downgrade.

The NU1603 warning about Elsa.Api.Client 3.7.0-preview.4523 not found -> 3.7.0-rc1 resolved instead is expected and benign — do not chase it.

Authentication — pick ONE login stack, not both

Elsa Studio 3.7 ships two login modules that BOTH register a /login route. Adding both raises System.InvalidOperationException: The following routes are ambiguous: 'login' in ... on first WASM render.

• Old (do not use): Elsa.Studio.Login.BlazorWasm + AddLoginModule() + Elsa.Studio.Login.HttpMessageHandlers.AuthenticatingApiHttpMessageHandler.
• New (use this): Elsa.Studio.Authentication.ElsaIdentity.BlazorWasm + AddElsaIdentity() and Elsa.Studio.Authentication.ElsaIdentity.UI + AddElsaIdentityUI() + Elsa.Studio.Authentication.ElsaIdentity.HttpMessageHandlers.ElsaIdentityAuthenticatingApiHttpMessageHandler.

You need BOTH .BlazorWasm (platform services / token accessor) AND .UI (login page + unauthorized-redirect handler). Missing .UI = shell shows "Unauthorized" with nowhere to go — no login screen.

Admin credentials — the empty-hash trap

Elsa.Identity uses config-based users with HashedPassword + HashedPasswordSalt. Leaving them as empty strings never validates — every login returns {"isAuthenticated":false} even with the "right" password.

Reference well-known hashes for admin / password (from Elsa.ServerAndStudio.Web/appsettings.json on the v3 branch of elsa-core):

"HashedPassword":     "TfKzh9RLix6FPcCNeHLkGrysFu3bYxqzGqduNdi8v1U=",
"HashedPasswordSalt": "JEy9kBlhHCNsencitRHlGxmErmSgY+FVyMJulCH27Ds="

Both are already in appsettings.json. To create a real user, generate a new hash + salt through Elsa's password hasher and overwrite via env var (Identity__Users__0__HashedPassword, Identity__Users__0__HashedPasswordSalt).

Behind Coolify's Traefik — forwarded headers are mandatory

Traefik terminates TLS and forwards the request as plain HTTP. Without configuring forwarded headers, Kestrel thinks it's serving HTTP and every generated URL (Blazor's apiUrl, redirects, links) comes out as http://, which the browser refuses to fetch from an HTTPS page ("Failed to fetch", mixed-content errors).

Fix (already in Program.cs):

builder.Services.Configure<ForwardedHeadersOptions>(o =>
{
    o.ForwardedHeaders = ForwardedHeaders.All;
    o.KnownNetworks.Clear();   // Traefik isn't in a known private range
    o.KnownProxies.Clear();
});
// ...
app.UseForwardedHeaders();  // must be BEFORE UseRouting / UseAuthentication

Setting ASPNETCORE_FORWARDEDHEADERS_ENABLED=true as an env var does the same thing but we prefer the code path so behaviour is source-controlled.

SPA fallback — carve out /elsa/api so 404s stay 404

MapFallbackToPage("/_Host") catches EVERYTHING no other endpoint claims, including unknown /elsa/api/* paths — which then return the Studio HTML with a 200 status, confusing anything that expects JSON.

Fix (already in Program.cs):

app.MapFallback("/elsa/api/{**rest}", () => Results.NotFound(new { error = "not_found" }));
app.MapFallbackToPage("/_Host");

Order matters — the API-specific fallback must be registered FIRST.

Studio → backend wiring

The WASM Studio reads its backend URL at runtime from a JS-injected client config, NOT from a compile-time constant. Pages/_Host.cshtml renders:

window.getClientConfig = function () { return { "apiUrl": "https://elsa.tes.gd/elsa/api" }; };

…assembled from Hosting:BaseUrl (or Http:BaseUrl) + Hosting:ApiPrefix (default elsa/api). Elsa.Studio.Wasm/Program.cs reads this via IJSRuntime after DI is set up and stuffs it into BackendOptions.Url. This lets the SAME compiled WASM point at any origin without a rebuild — set HTTP__BASEURL in Coolify env vars to change the target.

SQLite persistence — pin the path

UseSqlite() with no connection string writes to elsa.sqlite.db in the process working dir → /app/elsa.sqlite.db inside the container, which is OUTSIDE the mounted /app/App_Data volume. Every redeploy loses all state.

Fix (already in Program.cs): read ConnectionStrings:Sqlite (defaults to Data Source=App_Data/elsa.sqlite.db;Cache=Shared;) and pass it to ef.UseSqlite(sqliteConnectionString).

For anything real, move to Postgres — add Elsa.EntityFrameworkCore.PostgreSql NuGet, switch .UseSqlite(...) → .UsePostgreSql(...), provision a Coolify Postgres service and set ConnectionStrings__Sqlite (still the config key) to its DSN.

Coolify deployment quirks (repo-specific)

• App is built via POST /applications/public with build_pack=dockerfile — proper application, not a service. (POST /applications/dockercompose creates a "service" instead and lacks the clean docker_compose_domains handling — avoid.)
• git_repository is truncated to owner/repo.git on create. Always PATCH it back with the full https://user:token@host/owner/repo.git after. Confirm with a GET.
• docker_compose_raw (if you ever go that route) must be base64-encoded at create time. POST /applications/dockercompose rejects it otherwise.
• Deploys are fire-and-forget — never poll from Claude. User's global rule.

NATS activities

Connection details live on the activity nodes themselves — configured per-node in the workflow designer as a single connection string in the standard NATS URL form <scheme>://[user:password@]host[:port] (schemes: nats, tls, ws, wss). Every stored trigger carries its own connection string; a NatsConnectionCache singleton parses the string into (cleanUrl, user, password) and hands out one NatsConnection per unique tuple so repeat invocations reuse the same TCP/TLS session.

Passwords with special characters (@ : / #) must be URL-encoded (%40 %3A %2F %23). The activity's input Description shows this in the Studio property panel.

Files under src/Elsa.CustomServer/:

• Activities/NatsPublish.cs — publisher CodeActivity. Inputs: Connection (single connection string), Subject, Body, optional MessageId (sets the Nats-Msg-Id header for JetStream server-side dedup), optional ExpectedStream (fail-fast assertion). Outputs Sequence and Duplicate.
• Activities/NatsTrigger.cs — trigger Trigger<string>. Inputs: Connection, Stream, Subject (wildcards allowed). Outputs: Result = message body (UTF-8), ReceivedSubject, Headers. Its trigger name / stimulus name is NATS.NatsTrigger; the stimulus record includes the connection string so a message from server A only starts the workflows designed to listen on server A.
• Nats/NatsConnectionCache.cs — singleton connection-string parser + (cleanUrl, user, password) → NatsConnection cache. Exposes static ParseConnectionString(...) for anyone else who needs the same split.
• Nats/NatsTriggerHostedService.cs — one BackgroundService that scans ITriggerStore for stored triggers named NATS.NatsTrigger, spins up one durable pull consumer per unique stimulus, and dispatches workflows via IWorkflowDispatcher.DispatchAsync(DispatchTriggerWorkflowsRequest) as messages arrive. The mediator handler NatsTriggerIndexChangedHandler re-runs the scan whenever WorkflowTriggersIndexed fires (i.e. after publishing a workflow).

Consumer model: shared durable pull consumer with DurableName = elsa-<sanitizedStream>-<sanitizedSubject> and AckPolicy.Explicit. That means if multiple Elsa instances are running, exactly one processes each message (load-balanced), at-least-once. MaxDeliver = 5, AckWait = 30s, MaxAckPending = 256. Failed dispatches NAK with a 5-second delay.

Security note: trigger stimuli — including the NATS connection string, which typically embeds the password — are persisted in the trigger store DB. Don't log the stimulus record verbatim, and treat the trigger store with the same care as any secret storage.

Migration note: activities were changed from three fields (Url / User / Password) to a single Connection input. Any workflow authored against the old shape needs to be reopened in Studio and its NATS publish/trigger nodes re-filled — republishing then re-indexes the trigger store with the new stimulus shape.

Package: NATS.Net (v2 client). The v1 NATS.Client package does not support wss:// from .NET — do not use it.

Session-specific reminders

• Custom activities added under Activities/ in the SERVER project (not the WASM project). The server's assembly scan is the one that matters for the toolbox — Studio just reads descriptors over the API.
• Blazor WASM cache is stubborn. If a change doesn't show up after Ctrl+Shift+R, open the site in incognito to confirm whether it's a caching issue vs. a real failure to deploy.
• When Studio complains about auth, curl -X POST /elsa/api/identity/login first — if the API returns a JWT, the server is fine and the bug is client-side (module wiring, cache).