feat: allow overriding external domain

Author: dealloc

src/CommunityToolkit.Aspire.Hosting.Zitadel/README.md

@@ -20,15 +20,46 @@ Then, in the _Program.cs_ file of `AppHost`, define a Zitadel resource, then cal
 builder.AddZitadel("zitadel");
 ```
 
-Zitadel *requires* a Postgres database, you can add one with `AddDatabase`:
+Zitadel *requires* a Postgres database, you can add one with `WithDatabase`:
 ```csharp
 var database = builder.AddPostgres("postgres");
 
 builder.AddZitadel("zitadel")
-    .AddDatabase(database);
+    .WithDatabase(database);
 ```
 You can also pass in a database rather than server (`AddPostgres().AddDatabase()`).
 
+### Configuring the External Domain
+
+By default, Zitadel uses `{name}.dev.localhost` as the external domain, which works well for local development. For production deployments or custom scenarios, you can configure a custom external domain:
+
+**Option 1: Using the parameter**
+```csharp
+builder.AddZitadel("zitadel", externalDomain: "auth.example.com");
+```
+
+**Option 2: Using the fluent API**
+```csharp
+builder.AddZitadel("zitadel")
+    .WithExternalDomain("auth.example.com");
+```
+
+**Option 3: From configuration**
+```csharp
+var domain = builder.Configuration["Zitadel:ExternalDomain"];
+builder.AddZitadel("zitadel", externalDomain: domain);
+```
+
+#### Why `.dev.localhost`?
+
+`.dev.localhost` is a special top-level domain that:
+- Automatically resolves to `127.0.0.1` without requiring DNS configuration
+- Provides unique subdomains for each Zitadel instance (e.g., `zitadel1.dev.localhost`, `zitadel2.dev.localhost`)
+- Works reliably in local development and CI/CD environments
+- Satisfies Zitadel's requirement for stable hostnames in OIDC/OAuth2 flows
+
+For production deployments, replace this with your actual domain name using one of the configuration methods above.
+
 ## Feedback & contributing
 
 https://github.com/CommunityToolkit/Aspire

src/CommunityToolkit.Aspire.Hosting.Zitadel/ZitadelHostingExtensions.cs

@@ -17,18 +17,23 @@ public static class ZitadelHostingExtensions
     /// <param name="username">An optional parameter to set a username for the admin account, if <c>null</c> will auto generate one.</param>
     /// <param name="password">An optional parameter to set a password for the admin account, if <c>null</c> will auto generate one.</param>
     /// <param name="masterKey">An optional parameter to set the masterkey, if <c>null</c> will auto generate one.</param>
+    /// <param name="externalDomain">The external domain for Zitadel. Defaults to <c>{name}.dev.localhost</c> which works for local development. For production deployments, specify the actual domain (e.g., "auth.example.com").</param>
     public static IResourceBuilder<ZitadelResource> AddZitadel(
         this IDistributedApplicationBuilder builder,
         [ResourceName] string name,
         int? port = null,
         IResourceBuilder<ParameterResource>? username = null,
         IResourceBuilder<ParameterResource>? password = null,
-        IResourceBuilder<ParameterResource>? masterKey = null
+        IResourceBuilder<ParameterResource>? masterKey = null,
+        string? externalDomain = null
     )
     {
         ArgumentNullException.ThrowIfNull(builder);
         ArgumentNullException.ThrowIfNull(name);
 
+        // Use provided external domain or default to {name}.dev.localhost
+        var domain = externalDomain ?? $"{name}.dev.localhost";
+
         var usernameParameter = username?.Resource ?? new ParameterResource($"{name}-username", _ => "admin", false);
         var passwordParameter = password?.Resource ?? ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter(builder, $"{name}-password", minSpecial: 1);
         var masterKeyParameter = masterKey?.Resource ?? ParameterResourceBuilderExtensions.CreateGeneratedParameter(builder, $"{name}-masterKey", true, new GenerateParameterDefault
@@ -64,7 +69,7 @@ public static IResourceBuilder<ZitadelResource> AddZitadel(
             .WithEnvironment("ZITADEL_MASTERKEY", masterKeyParameter)
             .WithEnvironment("ZITADEL_TLS_ENABLED", "false")
             .WithEnvironment("ZITADEL_EXTERNALSECURE", "false")
-            .WithEnvironment("ZITADEL_EXTERNALDOMAIN", $"{name}.dev.localhost")
+            .WithEnvironment("ZITADEL_EXTERNALDOMAIN", domain)
             .WithUrlForEndpoint(ZitadelResource.HttpEndpointName, e => e.DisplayText = "Zitadel Dashboard");
 
         // Use ReferenceExpression for the port to avoid issues with endpoint allocation
@@ -121,4 +126,20 @@ public static IResourceBuilder<ZitadelResource> WithDatabase(this IResourceBuild
 
         return builder;
     }
+
+    /// <summary>
+    /// Configures the external domain for the Zitadel resource. This overrides the default domain set in <see cref="AddZitadel"/>.
+    /// </summary>
+    /// <param name="builder">The Zitadel resource builder.</param>
+    /// <param name="externalDomain">The external domain to use (e.g., "auth.example.com"). Cannot be null or empty.</param>
+    /// <returns>The resource builder for chaining.</returns>
+    /// <exception cref="ArgumentException">Thrown if <paramref name="externalDomain"/> is null or whitespace.</exception>
+    public static IResourceBuilder<ZitadelResource> WithExternalDomain(
+        this IResourceBuilder<ZitadelResource> builder,
+        string externalDomain)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(externalDomain);
+
+        return builder.WithEnvironment("ZITADEL_EXTERNALDOMAIN", externalDomain);
+    }
 }

tests/CommunityToolkit.Aspire.Hosting.Zitadel.Tests/ZitadelHostingExtensionsTests.cs

@@ -127,4 +127,76 @@ public void AddZitadel_With_Custom_Port()
 
         Assert.Equal(8888, endpoint.Port);
     }
+
+    [Fact]
+    public async Task AddZitadel_Uses_Custom_ExternalDomain()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        var zitadel = builder.AddZitadel("zitadel", externalDomain: "auth.example.com");
+
+        var env = await zitadel.Resource.GetEnvironmentVariableValuesAsync();
+
+        Assert.Equal("auth.example.com", env["ZITADEL_EXTERNALDOMAIN"]);
+    }
+
+    [Fact]
+    public async Task WithExternalDomain_Overrides_Default()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        var zitadel = builder.AddZitadel("zitadel")
+            .WithExternalDomain("custom.domain.com");
+
+        var env = await zitadel.Resource.GetEnvironmentVariableValuesAsync();
+
+        Assert.Equal("custom.domain.com", env["ZITADEL_EXTERNALDOMAIN"]);
+    }
+
+    [Fact]
+    public async Task WithExternalDomain_Can_Override_Parameter()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        var zitadel = builder.AddZitadel("zitadel", externalDomain: "first.example.com")
+            .WithExternalDomain("second.example.com");
+
+        var env = await zitadel.Resource.GetEnvironmentVariableValuesAsync();
+
+        // WithExternalDomain should override the parameter
+        Assert.Equal("second.example.com", env["ZITADEL_EXTERNALDOMAIN"]);
+    }
+
+    [Fact]
+    public void WithExternalDomain_Throws_If_Null()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+        var zitadel = builder.AddZitadel("zitadel");
+
+        var act = () => zitadel.WithExternalDomain(null!);
+
+        Assert.Throws<ArgumentNullException>(act);
+    }
+
+    [Fact]
+    public void WithExternalDomain_Throws_If_Empty()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+        var zitadel = builder.AddZitadel("zitadel");
+
+        var act = () => zitadel.WithExternalDomain("");
+
+        Assert.Throws<ArgumentException>(act);
+    }
+
+    [Fact]
+    public void WithExternalDomain_Throws_If_Whitespace()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+        var zitadel = builder.AddZitadel("zitadel");
+
+        var act = () => zitadel.WithExternalDomain("   ");
+
+        Assert.Throws<ArgumentException>(act);
+    }
 }