Add onboarding, deployment, and security documentation#129
Conversation
Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com>
Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com>
Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com>
Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **elsa-configmap.yaml:** | ||
| ```yaml | ||
| apiVersion: v1 | ||
| kind: ConfigMap | ||
| metadata: | ||
| name: elsa-config | ||
| data: | ||
| appsettings.Production.json: | | ||
| { | ||
| "ConnectionStrings": { | ||
| "PostgreSql": "Host=postgres;Database=elsa_workflows;Username=elsa_user;Password=$(POSTGRES_PASSWORD)" | ||
| }, |
There was a problem hiding this comment.
The ConfigMap example writes "Password=$(POSTGRES_PASSWORD)" directly into appsettings.Production.json, but Kubernetes does not substitute env vars inside ConfigMap file content and the default .NET configuration provider will read the literal string. Following this snippet results in the app trying to log into PostgreSQL with the password $(POSTGRES_PASSWORD) and failing authentication; the secret is never applied. The connection string needs to be built from an env var at runtime or injected via Secret/ValueFrom rather than embedded as a placeholder in the JSON.
Useful? React with 👍 / 👎.
| # Add a migration | ||
| dotnet ef migrations add InitialElsa --context ManagementElsaDbContext | ||
| dotnet ef migrations add InitialElsaRuntime --context RuntimeElsaDbContext | ||
|
|
There was a problem hiding this comment.
The production migration instructions run dotnet ef migrations add InitialElsa for both ManagementElsaDbContext and RuntimeElsaDbContext. EF Core requires migration names to be unique per assembly, so the second command will fail with “A migration named 'InitialElsa' already exists” (or overwrite the first migration if forced). Users following these steps cannot create migrations for both contexts. Use distinct names or separate output folders for each context.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive onboarding, deployment, and security documentation to help users integrate Elsa Workflows into their applications. It addresses several community-reported issues with detailed, practical guides totaling 3,452 lines of new documentation.
Key Changes:
- Onboarding guide for integrating Elsa into existing ASP.NET Core applications, including detailed solutions for common pain points like DbContext conflicts and Swagger schema issues
- Kubernetes deployment guide with PostgreSQL configuration, explaining why connection strings alone are insufficient and providing troubleshooting for common misconfigurations
- Security guides covering both disabling authentication for development and integrating with external identity providers (Microsoft Entra ID, Auth0, Keycloak)
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| SUMMARY.md | Adds navigation entries for new Onboarding, Deployment, Integration, and Security sections |
| guides/onboarding/hosting-elsa-in-existing-app.md | Comprehensive guide for adding Elsa to existing ASP.NET Core apps with solutions to DbContextOptions conflicts, version pinning issues, and Swagger schema conflicts |
| guides/onboarding/README.md | Index page for onboarding section |
| guides/deployment/kubernetes.md | Detailed Kubernetes deployment guide with PostgreSQL setup, explaining module-level provider configuration and troubleshooting connection/migration issues |
| guides/deployment/README.md | Index page for deployment section |
| guides/integration/blazor-dashboard.md | Guide for integrating Elsa Studio with Blazor Server, covering hosting patterns and authentication configuration |
| guides/integration/README.md | Index page for integration section |
| guides/security/disable-auth.md | Development-focused guide for disabling authentication with clear production warnings and multiple configuration approaches |
| guides/security/external-identity-providers.md | Foundational guide for OIDC/OAuth2 integration with provider-specific examples for Microsoft Entra ID, Auth0, and Keycloak |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // Note: Only forward to the same domain or explicitly trusted domains | ||
| var cookies = httpContext.Request.Headers["Cookie"].FirstOrDefault(); | ||
| if (!string.IsNullOrEmpty(cookies) && IsElsaServerTrusted(client.BaseAddress)) | ||
| { | ||
| // Filter to only authentication-related cookies if needed | ||
| client.DefaultRequestHeaders.TryAddWithoutValidation("Cookie", cookies); | ||
| } | ||
| } | ||
| }); | ||
| }); | ||
|
|
||
| // Helper method to validate Elsa Server is trusted | ||
| bool IsElsaServerTrusted(Uri baseAddress) | ||
| { | ||
| // Only forward cookies to same origin or explicitly configured trusted domains | ||
| var trustedDomains = builder.Configuration.GetSection("ElsaServer:TrustedDomains").Get<string[]>() | ||
| ?? Array.Empty<string>(); | ||
|
|
||
| return trustedDomains.Contains(baseAddress.Host, StringComparer.OrdinalIgnoreCase) | ||
| || baseAddress.Host == "localhost" | ||
| || baseAddress.Host == "127.0.0.1"; | ||
| }); | ||
| }); |
There was a problem hiding this comment.
The cookie forwarding example forwards all cookies to potentially untrusted domains. The IsElsaServerTrusted helper method is defined but the closing braces are incorrect - there are two extra closing braces on lines 635-636 that create invalid syntax. Additionally, the validation logic should be more explicit about only forwarding authentication-specific cookies, not all cookies which could include session tokens or other sensitive data.
There was a problem hiding this comment.
Fixed in commit fe6fda0. Removed the two extra closing braces on lines 635-636 that were causing the syntax error.
| studio.DisableAuthorization = true; // Development only | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
The troubleshooting suggestion references a DisableAuthorization property on Studio configuration, but this property is not shown in any of the earlier code examples in the document. If this property exists, it should be demonstrated in the main configuration examples. If it doesn't exist or is hypothetical, the suggestion should be clarified or corrected.
There was a problem hiding this comment.
Fixed in commit fe6fda0. Replaced the incorrect DisableAuthorization property reference with the correct pattern shown in earlier examples (ConfigureHttpClient with no authentication).
| command: ["/bin/sh", "-c"] | ||
| args: | ||
| - | | ||
| dotnet ef database update --context ManagementElsaDbContext | ||
| dotnet ef database update --context RuntimeElsaDbContext | ||
| env: | ||
| - name: ConnectionStrings__PostgreSql | ||
| value: "Host=postgres;Database=elsa_workflows;Username=elsa_user;Password=$(POSTGRES_PASSWORD)" | ||
| - name: POSTGRES_PASSWORD | ||
| valueFrom: | ||
| secretKeyRef: | ||
| name: postgres-secret | ||
| key: password | ||
| restartPolicy: OnFailure | ||
| ``` |
There was a problem hiding this comment.
Similar to the init container example, the migration Job assumes the Elsa Server image includes EF Core tooling (dotnet ef). This is often not the case in production images. Consider adding a note that this approach requires the dotnet-ef tool to be installed in the image, or recommend using a separate migration image that includes the necessary tooling.
There was a problem hiding this comment.
Added the warning in commit fe6fda0. Similar to the init container, the Job example now includes a clear warning about the dotnet-ef requirement.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
… warnings Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com>
Implementation: Add Onboarding and Deployment Documentation ✅
This PR implements "PR 5" from the planning document, adding comprehensive onboarding, deployment, integration, and security documentation to address issues #6, #75, #87, #15, and #16.
Summary
Added five new comprehensive documentation files totaling 3,452 lines of documentation with all PR review feedback addressed.
Latest Updates - Addressing All PR Review Feedback ✅
All 8 PR Review Comments Addressed:
Documentation Files
Hosting Elsa in an Existing App (655 lines) - Addresses issue Significant Onboarding Gaps #6
Kubernetes Deployment Basics (908+ lines) - Addresses issue k8s deployment issue #75
Blazor Dashboard Integration (729 lines) - Addresses issue [DOC] Detailed procedures to integrate Elas dashboard with .net 8.0 Blazor apps #87
Disable Auth in Development (523 lines) - Addresses issue How to disable authentication for Elsa Server + Elsa Studio #15
External Identity Providers (586 lines) - Partially addresses issue Third party Identity Provider Integration #16
Issues Addressed
Original prompt
Implement "PR 5" from our prior planning for elsa-workflows/elsa-gitbook.
Goal: Add onboarding and deployment documentation to help users integrate Elsa into existing ASP.NET Core applications, deploy to Kubernetes (including PostgreSQL configuration), and understand basic authentication options (including how to disable auth in dev and how to integrate with external identity later). This should directly address pain points raised in issues #6, #75, #87, #15, and partially #16.
Repository: elsa-workflows/elsa-gitbook
Base branch: main
Requirements:
Onboarding guide for hosting Elsa in an existing ASP.NET Core app (issue Significant Onboarding Gaps #6)
guides/onboarding/hosting-elsa-in-existing-app.md.services.AddElsa(...)/ module configuration inProgram.cs.DbContextOptions<T>requirement forAppDbContextwhen using EF Core.Kubernetes deployment basics with PostgreSQL (issue k8s deployment issue #75)
guides/deployment/kubernetes.md.scripts/Kubernetes manifests in elsa-core (if present) at a high level.Program.cs.Blazor dashboard integration basics (issue [DOC] Detailed procedures to integrate Elas dashboard with .net 8.0 Blazor apps #87)
guides/integration/blazor-dashboard.md./elsa.Disable auth in dev (issue How to disable authentication for Elsa Server + Elsa Studio #15)
guides/security/disable-auth.md.External identity providers stub (partial issue Third party Identity Provider Integration #16)
guides/security/external-identity-providers.md.Navigation updates
SUMMARY.mdto add:guides/onboarding/hosting-elsa-in-existing-app.md(e.g., "Hosting Elsa in an existing app").This pull request was created as a result of the following prompt from Copilot chat.
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.