Refactor Docker registry parameters for consistency and clarity in deployment workflow

devlinj678 · devlinj678 · commit 7545420b1f2e · 2025-12-18T07:56:41.000-08:00
Enhance README with detailed usage scenarios and examples for SSH deployment
Update DockerSSHPipeline to streamline deployment steps and remove unnecessary dependencies
diff --git a/.github/workflows/deploy-Production.yml b/.github/workflows/deploy-Production.yml
@@ -39,10 +39,10 @@ jobs:
         env:
           DockerSSH__TargetHost: ${{ secrets.TARGET_HOST }}
           DockerSSH__SshUsername: ${{ secrets.SSH_USERNAME }}
-          Parameters__registry_endpoint: ghcr.io
-          Parameters__registry_repository: ${{ github.repository }}
-          Parameters__registry_username: ${{ github.actor }}
-          Parameters__registry_password: ${{ secrets.GITHUB_TOKEN }}
+          DockerRegistry__RegistryUrl: ghcr.io
+          DockerRegistry__RepositoryPrefix: ${{ github.repository }}
+          DockerRegistry__RegistryUsername: ${{ github.actor }}
+          DockerRegistry__RegistryPassword: ${{ secrets.GITHUB_TOKEN }}
           IMAGE_TAG_SUFFIX: build.${{ github.run_number }}.${{ env.SHORT_SHA }}
           Parameters__p: ${{ vars.PARAMETERS_P }}
           Parameters__cache-password: ${{ secrets.PARAMETERS_CACHE_PASSWORD }}
diff --git a/README.md b/README.md
@@ -13,6 +13,41 @@ flowchart LR
     A[Dev Machine / CI<br/>aspire deploy] -->|SSH| B[Target Server<br/>docker compose up]
 ```
 
+## How It Works
+
+The deployment pipeline executes in phases, with steps running in parallel where possible:
+
+```mermaid
+flowchart TD
+    subgraph Configure
+        A[Establish SSH] --> B[Configure Deployment]
+        C[Process Parameters] --> D[Build Prerequisites]
+    end
+
+    subgraph Build & Push
+        D --> E[Build Images]
+        E --> F[Push to Registry]
+    end
+
+    subgraph Deploy
+        F --> G[Prepare Compose Files]
+        G --> H[Transfer Files via SCP]
+        H --> I[docker compose up]
+        I --> J[Health Checks]
+    end
+
+    J --> K[Done]
+```
+
+**Phase breakdown:**
+1. **Configure** - Establish SSH connection, gather parameters (registry, credentials, deploy path)
+2. **Build** - Build container images for each project in parallel
+3. **Push** - Push images to the configured container registry
+4. **Deploy** - Transfer compose files and `.env` to the remote server, run `docker compose up`
+5. **Verify** - Run health checks, extract dashboard token, cleanup SSH
+
+Run `aspire do diagnostics` to see the full dependency graph for your application.
+
 ## Quick Start
 
 1. Add the package feed:
diff --git a/samples/DockerPipelinesSample/DockerPipelinesSample.AppHost/AppHost.cs b/samples/DockerPipelinesSample/DockerPipelinesSample.AppHost/AppHost.cs
@@ -1,81 +1,22 @@
 #pragma warning disable ASPIREPIPELINES003 // WithDeploymentImageTag is experimental
-#pragma warning disable ASPIRECOMPUTE003 // ContainerRegistryResource is experimental
 
-// =============================================================================
 // Sample: SSH Deployment to Remote Docker Host
-// =============================================================================
+// Demonstrates: custom image tagging, YARP reverse proxy, optional HTTPS with Let's Encrypt
 //
-// This sample demonstrates deploying an Aspire application to a remote Docker
-// host via SSH with the following features:
-//
-// - Custom image tagging from CI/CD pipelines
-// - Container registry integration with automatic login
-// - YARP reverse proxy as the public entry point
-// - Optional HTTPS with automatic Let's Encrypt certificate generation
-//
-// Configuration (appsettings.json or environment variables):
-// ----------------------------------------------------------
-// - EnableHttps: Set to "true" to enable HTTPS with Let's Encrypt certificates.
-//                When false (default), only HTTP on port 80 is exposed.
-//
-// Required parameters for deployment:
-// - Parameters__registry-endpoint: Registry URL (e.g., "registry.digitalocean.com")
-// - Parameters__registry-repository: Repository prefix (e.g., "my-project")
-// - Parameters__registry-username: Registry username
-// - Parameters__registry-password: Registry password (secret)
-//
-// Required parameters when EnableHttps=true:
-// - Parameters__domain: The domain name for the certificate (e.g., "example.com")
-// - Parameters__letsencrypt_email: Email for Let's Encrypt registration/notifications
-//
-// How container registry integration works:
-// -----------------------------------------
-// 1. A ContainerRegistryResource is created with endpoint and repository
-// 2. WithCredentialsLogin adds a login step that runs before push-prereq
-// 3. Built-in push steps (push-apiservice, push-webfrontend) push to the registry
-// 4. Remote deployment authenticates with the same credentials to pull images
-//
-// How HTTPS works:
-// ----------------
-// When EnableHttps is true, a certbot container is added that:
-// 1. Runs the Let's Encrypt ACME HTTP-01 challenge on port 80
-// 2. Obtains/renews certificates and stores them in a shared Docker volume
-// 3. Sets permissions so non-root containers can read the certificates
-// 4. Exits after certificate generation
-//
-// YARP then starts (after certbot completes) and:
-// - Mounts the shared certificate volume (read-only)
-// - Serves HTTPS on port 443 using the Let's Encrypt certificates
-// - Serves HTTP on port 80
-//
-// On subsequent deployments, certbot skips certificate generation if valid
-// certificates already exist (--keep-until-expiring flag).
-//
-// =============================================================================
+// Key settings:
+// - IMAGE_TAG_SUFFIX: Custom image tag (e.g., "build.42.abc1234")
+// - EnableHttps: Enable HTTPS with Let's Encrypt (requires domain + email parameters)
+// - DockerRegistry__*: Registry URL, prefix, and optional credentials
 
 var builder = DistributedApplication.CreateBuilder(args);
 
-// Custom image tag from CI/CD (e.g., IMAGE_TAG_SUFFIX=build.42.abc1234)
 var imageTag = builder.Configuration["IMAGE_TAG_SUFFIX"];
 
-// Container registry configuration for push/pull operations
-// These parameters are prompted during deployment or can be set via config
-var registryEndpoint = builder.AddParameter("registry-endpoint");
-var registryRepository = builder.AddParameter("registry-repository");
-
-var registryUsername = builder.AddParameter("registry-username");
-var registryPassword = builder.AddParameter("registry-password", secret: true);
-
-// Create container registry with automatic login
-// This creates a login-to-registry step that runs before built-in push steps
-var registry = builder.AddContainerRegistry("registry", registryEndpoint, registryRepository)
-    .WithCredentialsLogin(registryUsername, registryPassword);
-
-// Configure Docker Compose environment with SSH deployment support
+// Configure Docker Compose environment with SSH deployment
+// Registry is automatically configured from DockerRegistry:* settings
 builder.AddDockerComposeEnvironment("env")
     .WithDashboard(db => db.WithHostPort(8085))
-    .WithSshDeploySupport()
-    .WithContainerRegistry(registry);
+    .WithSshDeploySupport();
 
 var p = builder.AddParameter("p");
 
@@ -99,7 +40,7 @@
           c.AddRoute(frontend);
       });
 
-// Apply the image tag to all services if specified
+// Apply custom image tag from CI/CD to all services
 if (!string.IsNullOrEmpty(imageTag))
 {
     apiService.WithImagePushOptions(c => c.Options.RemoteImageTag = imageTag);
@@ -113,28 +54,18 @@
 
     if (enableHttps)
     {
-        // Let's Encrypt parameters (required when EnableHttps=true)
-        // Set via: Parameters__domain and Parameters__letsencrypt_email
         var domain = builder.AddParameter("domain");
         var letsEncryptEmail = builder.AddParameter("letsencrypt-email");
 
-        // Certbot container for automatic Let's Encrypt certificate generation
-        // Uses the official certbot/certbot image to obtain and renew certificates.
-        //
-        // Certbot arguments explained:
-        // - certonly: Only obtain the certificate, don't install it
-        // - --standalone: Run a temporary webserver for the ACME HTTP-01 challenge
-        // - --non-interactive: Don't prompt for user input
-        // - --agree-tos: Agree to Let's Encrypt Terms of Service
-        // - --keep-until-expiring: Skip if cert exists and is not within 30 days of expiry
-        // - --deploy-hook: Command to run after successful cert issuance (fix permissions)
-        // - --email: Email for urgent renewal/security notices
-        // - -d: Domain name for the certificate
-        //
+        // Certbot container for automatic Let's Encrypt certificate generation.
+        // How it works:
+        // 1. Certbot starts and binds to port 80 for the ACME HTTP-01 challenge
+        // 2. Let's Encrypt verifies domain ownership by requesting /.well-known/acme-challenge/
+        // 3. Certificates are stored in a shared Docker volume (/etc/letsencrypt)
+        // 4. Certbot fixes permissions so non-root containers can read the certs, then exits
+        // 5. On subsequent deploys, --keep-until-expiring skips renewal if certs are still valid
         var certbot = builder.AddContainer("certbot", "certbot/certbot")
-            // Shared volume for certificates - both certbot and YARP mount this
             .WithVolume("letsencrypt", "/etc/letsencrypt")
-            // Port 80 must be published to host for Let's Encrypt to reach the ACME challenge
             .WithHttpEndpoint(port: 80, targetPort: 80)
             .WithExternalHttpEndpoints()
             .WithArgs(context =>
@@ -145,7 +76,6 @@
                 context.Args.Add("--agree-tos");
                 context.Args.Add("-v");
                 context.Args.Add("--keep-until-expiring");
-                // Fix permissions so non-root containers (like YARP) can read the certs
                 context.Args.Add("--deploy-hook");
                 context.Args.Add("chmod -R 755 /etc/letsencrypt/live && chmod -R 755 /etc/letsencrypt/archive");
                 context.Args.Add("--email");
@@ -154,28 +84,21 @@
                 context.Args.Add(domain.Resource);
             });
 
-        // Certbot and YARP both need port 80, but at different times:
-        // - Certbot needs port 80 during the ACME challenge (runs first, then exits)
-        // - YARP needs port 80 for HTTP traffic (starts after certbot completes)
-        // WaitForCompletion ensures YARP doesn't start until certbot exits successfully
+        // YARP waits for certbot to complete since both need port 80.
+        // Certbot runs the ACME challenge first, then YARP takes over for traffic.
         yarp.WaitForCompletion(certbot);
-
         yarp.WithHostPort(80);
         yarp.WithHttpsEndpoint(443);
-
-        // Mount the shared certificate volume (read-only since YARP only reads certs)
         yarp.WithVolume("letsencrypt", "/etc/letsencrypt", isReadOnly: true);
 
         // Configure Kestrel to use the Let's Encrypt certificates
-        // Certbot stores certs at: /etc/letsencrypt/live/{domain}/
         yarp.WithEnvironment(context =>
         {
             context.EnvironmentVariables["Kestrel__Certificates__Default__Path"] =
                 ReferenceExpression.Create($"/etc/letsencrypt/live/{domain}/fullchain.pem");
             context.EnvironmentVariables["Kestrel__Certificates__Default__KeyPath"] =
                 ReferenceExpression.Create($"/etc/letsencrypt/live/{domain}/privkey.pem");
 
-            // Configure URLs for both HTTP and HTTPS
             var httpEndpoint = yarp.GetEndpoint("http");
             var httpsEndpoint = yarp.GetEndpoint("https");
 
@@ -189,7 +112,7 @@
     }
     else
     {
-        // HTTP only
+        // HTTP only mode - expose YARP on port 80
         yarp.WithHostPort(80);
     }
 
diff --git a/src/Aspire.Hosting.Docker.SshDeploy/DockerPipelineExtensions.cs b/src/Aspire.Hosting.Docker.SshDeploy/DockerPipelineExtensions.cs
@@ -1,10 +1,13 @@
 #pragma warning disable ASPIREPIPELINES004
+#pragma warning disable ASPIRECOMPUTE003
 
 using Aspire.Hosting.ApplicationModel;
 using Aspire.Hosting.Docker;
 using Aspire.Hosting.Docker.SshDeploy.Abstractions;
 using Aspire.Hosting.Docker.SshDeploy.Infrastructure;
 using Aspire.Hosting.Docker.SshDeploy.Services;
+using Aspire.Hosting.Eventing;
+using Aspire.Hosting.Lifecycle;
 using Aspire.Hosting.Pipelines;
 using Aspire.Hosting.Utils;
 using Microsoft.Extensions.Configuration;
@@ -65,20 +68,22 @@ public static class DockerPipelineExtensions
     public static IResourceBuilder<DockerComposeEnvironmentResource> WithSshDeploySupport(
         this IResourceBuilder<DockerComposeEnvironmentResource> resourceBuilder)
     {
+        var builder = resourceBuilder.ApplicationBuilder;
+
         // Register infrastructure services (shared across all environments)
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<IProcessExecutor, ProcessExecutor>();
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<IFileSystem, FileSystemAdapter>();
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<DockerCommandExecutor>();
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<SSHConfigurationDiscovery>();
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<GitHubActionsGeneratorService>();
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<ISshKeyDiscoveryService, SshKeyDiscoveryService>();
+        builder.Services.TryAddSingleton<IProcessExecutor, ProcessExecutor>();
+        builder.Services.TryAddSingleton<IFileSystem, FileSystemAdapter>();
+        builder.Services.TryAddSingleton<DockerCommandExecutor>();
+        builder.Services.TryAddSingleton<SSHConfigurationDiscovery>();
+        builder.Services.TryAddSingleton<GitHubActionsGeneratorService>();
+        builder.Services.TryAddSingleton<ISshKeyDiscoveryService, SshKeyDiscoveryService>();
 
         // Register both SSH connection factory implementations
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<NativeSSHConnectionFactory>();
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<SSHNetConnectionFactory>();
+        builder.Services.TryAddSingleton<NativeSSHConnectionFactory>();
+        builder.Services.TryAddSingleton<SSHNetConnectionFactory>();
 
         // Register the ISSHConnectionFactory interface - selects native ssh by default, SSH.NET as fallback
-        resourceBuilder.ApplicationBuilder.Services.TryAddSingleton<ISSHConnectionFactory>(sp =>
+        builder.Services.TryAddSingleton<ISSHConnectionFactory>(sp =>
         {
             var config = sp.GetRequiredService<IConfiguration>();
             var useLegacy = config.GetValue<bool>("DockerSSH:UseLegacySshNet", false);
@@ -92,7 +97,7 @@ public static IResourceBuilder<DockerComposeEnvironmentResource> WithSshDeploySu
         });
 
         // Register DockerSSHPipeline as a keyed service (one per resource)
-        resourceBuilder.ApplicationBuilder.Services.AddKeyedSingleton(
+        builder.Services.AddKeyedSingleton(
             resourceBuilder.Resource,
             (sp, key) => new DockerSSHPipeline(
                 (DockerComposeEnvironmentResource)key,
@@ -106,6 +111,63 @@ public static IResourceBuilder<DockerComposeEnvironmentResource> WithSshDeploySu
                 sp.GetRequiredService<IHostEnvironment>(),
                 sp.GetRequiredService<ILoggerFactory>()));
 
+        // Only configure registry in publish mode to avoid prompts during run mode
+        if (builder.ExecutionContext.IsPublishMode)
+        {
+            // Create default registry with parameters upfront
+            var config = builder.Configuration;
+            var registryUrlConfig = config["DockerRegistry:RegistryUrl"];
+            var repositoryPrefixConfig = config["DockerRegistry:RepositoryPrefix"];
+            var registryUsername = config["DockerRegistry:RegistryUsername"];
+            var registryPassword = config["DockerRegistry:RegistryPassword"];
+
+            var registryUrlParam = string.IsNullOrEmpty(registryUrlConfig)
+                ? builder.AddParameter($"registryUrl")
+                : builder.AddParameter($"registryUrl", registryUrlConfig);
+
+            var repositoryPrefixParam = string.IsNullOrEmpty(repositoryPrefixConfig)
+                ? builder.AddParameter($"repositoryPrefix")
+                : builder.AddParameter($"repositoryPrefix", repositoryPrefixConfig);
+
+            var defaultRegistry = builder.AddContainerRegistry(
+                $"default-registry-{resourceBuilder.Resource.Name}",
+                registryUrlParam,
+                repositoryPrefixParam);
+
+            // Add credentials login only if both username and password are configured
+            IResourceBuilder<ParameterResource>? usernameParam = null;
+            IResourceBuilder<ParameterResource>? passwordParam = null;
+            if (!string.IsNullOrEmpty(registryUsername) && !string.IsNullOrEmpty(registryPassword))
+            {
+                usernameParam = builder.AddParameter($"default-registry-username-{resourceBuilder.Resource.Name}", registryUsername);
+                passwordParam = builder.AddParameter($"default-registry-password-{resourceBuilder.Resource.Name}", registryPassword, secret: true);
+
+                defaultRegistry.WithCredentialsLogin(usernameParam, passwordParam);
+            }
+
+            // Subscribe to BeforeStartEvent to attach or remove default registry based on user configuration
+            var dockerEnvResource = resourceBuilder.Resource;
+            builder.Eventing.Subscribe<BeforeStartEvent>((@event, ct) =>
+            {
+                // Check if user already attached a registry via WithContainerRegistry()
+                if (dockerEnvResource.TryGetLastAnnotation<ContainerRegistryReferenceAnnotation>(out _))
+                {
+                    // User specified their own registry - remove our default resources
+                    builder.Resources.Remove(defaultRegistry.Resource);
+                    builder.Resources.Remove(registryUrlParam.Resource);
+                    builder.Resources.Remove(repositoryPrefixParam.Resource);
+                    if (usernameParam != null) builder.Resources.Remove(usernameParam.Resource);
+                    if (passwordParam != null) builder.Resources.Remove(passwordParam.Resource);
+                    return Task.CompletedTask;
+                }
+
+                // Attach the default registry
+                dockerEnvResource.Annotations.Add(new ContainerRegistryReferenceAnnotation(defaultRegistry.Resource));
+
+                return Task.CompletedTask;
+            });
+        }
+
         return resourceBuilder.WithPipelineStepFactory(context =>
         {
             var pipeline = context.PipelineContext.Services.GetRequiredKeyedService<DockerSSHPipeline>(resourceBuilder.Resource);
diff --git a/src/Aspire.Hosting.Docker.SshDeploy/DockerSSHPipeline.cs b/src/Aspire.Hosting.Docker.SshDeploy/DockerSSHPipeline.cs
@@ -131,14 +131,26 @@ public IEnumerable<PipelineStep> CreateSteps(PipelineStepFactoryContext context)
 
     public Task ConfigurePipelineAsync(PipelineConfigurationContext context)
     {
-        var dockerComposeUpStep = context.Steps.FirstOrDefault(s => s.Name == $"docker-compose-up-{DockerComposeEnvironment.Name}");
+        var dockerComposeUpStepName = $"docker-compose-up-{DockerComposeEnvironment.Name}";
+        var sshDeployStepName = $"deploy-docker-ssh-{DockerComposeEnvironment.Name}";
+
+        var dockerComposeUpStep = context.Steps.FirstOrDefault(s => s.Name == dockerComposeUpStepName);
         var deployStep = context.Steps.FirstOrDefault(s => s.Name == WellKnownPipelineSteps.Deploy);
         var prepareStep = context.Steps.FirstOrDefault(s => s.Name == $"prepare-{DockerComposeEnvironment.Name}");
 
-        // Remove docker compose up from the deployment pipeline
-        // not needed for SSH deployment
-        deployStep?.DependsOnSteps.Remove($"docker-compose-up-{DockerComposeEnvironment.Name}");
+        // Remove docker compose up from the deployment pipeline - not needed for SSH deployment
+        deployStep?.DependsOnSteps.Remove(dockerComposeUpStepName);
         dockerComposeUpStep?.RequiredBySteps.Remove(WellKnownPipelineSteps.Deploy);
+        dockerComposeUpStep?.DependsOnSteps.Clear();
+        dockerComposeUpStep?.RequiredBySteps.Clear();
+
+        // Remove print-summary steps from the deploy graph - they're for local output only
+        foreach (var step in context.Steps.Where(s => s.Tags.Contains("print-summary")))
+        {
+            step.DependsOnSteps.Clear();
+            step.RequiredBySteps.Clear();
+            deployStep?.DependsOnSteps.Remove(step.Name);
+        }
 
         // Make the built-in prepare step depend on our prerequisites check
         // This ensures Docker is available before building images
diff --git a/src/Aspire.Hosting.Docker.SshDeploy/README.md b/src/Aspire.Hosting.Docker.SshDeploy/README.md
