Add support for docker static files #12265

eerhardt · 2025-10-21T22:35:57Z

Description

This allows a resource that contains static files (for example a Javascript frontend) to embed its static files into another app server - for example a fastapi python app backend.

Key changes:

Add ContainerFilesSourceAnnotation which goes on the resource that can produce static files. A resource with this annotation builds a docker image, but the image doesn't get pushed to a registry.
Add ContainerFilesDestinationAnnotation which goes on the resource that receives the static files. Resources that support this COPY the static files from the source resource into their own docker image.
All compute environment resources respect the new StaticDockerFilesAnnotation to mean that this resource shouldn't be considered a compute resource.
AzureEnvironment only builds "build-only" containers, but doesn't push them.

Contributes to #12162

Checklist

Is this feature complete?
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
Does the change make any security assumptions or guarantees?
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire-docs issue (consider using one of the following templates):
    - [New article]: Add docs for PublishWithContainerFiles docs-aspire#5351

github-actions · 2025-10-21T22:36:14Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12265

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12265"

src/Aspire.Hosting.NodeJs/NodeAppResource.cs

src/Aspire.Hosting/ApplicationModel/StaticDockerFilesAnnotation.cs

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

src/Aspire.Hosting/ApplicationModel/DistributedApplicationModelExtensions.cs

davidfowl · 2025-10-22T01:07:37Z

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

+    /// <param name="appDirectory">The directory containing the Python application files.</param>
+    /// <param name="moduleName"></param>
+    /// <returns>A resource builder for further configuration of the Uvicorn Python application resource.</returns>
+    public static IResourceBuilder<PythonAppResource> AddUvicornApp(


We'll need to decide if we make this UvicornAppResource : PythonAppResource

What would be the advantage to doing this?

We can build extension methods that target unvicorn configuration. We'll want that but lets file a follow up issue.

eerhardt · 2025-10-22T19:54:10Z

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

+    public static IResourceBuilder<PythonAppResource> AddUvicornApp(
+        this IDistributedApplicationBuilder builder, [ResourceName] string name, string appDirectory, string moduleName)
+    {
+        var resourceBuilder = builder.AddPythonExecutable(name, appDirectory, "uvicorn")


@adamint - is this going to cause a problem with VS Code debugging?

aspire/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

Lines 322 to 323 in 5a87acf

// VS Code debug support - only applicable for Script and Module types

if (entrypointType is EntrypointType.Script or EntrypointType.Module)

Yes, we cannot debug any python executable. You'll need to call WithVSCodeDebugSupport and in the launch configuration provide the right entrypoint and then uvicorn as the module

We an switch to a module instead

We don't need to switch, we just need to indicate to the AppHost to start the right module

OR, we can switch and make it just work in all cases :)

I'm just not sure if there are performance differences between using the uvicorn executable and running as a python module

This allows a resource that contains files (for example a Javascript frontend) to embed its files into another app server - for example a fastapi python app backend. Key changes: * Add ContainerFilesSourceAnnotation which goes on the resource that can produce files. A resource with this annotation builds a docker image, but the image doesn't get pushed to a registry. * Add ContainerFilesDestinationAnnotation which goes on the resource that receives the files. Resources that support this COPY the static files from the source resource into their own docker image. * All compute environment resources respect a new HasEntrypoint=false bool to mean that this resource shouldn't be considered a compute resource, but should still build an image. Contributes to dotnet#12162

eerhardt · 2025-10-24T00:00:56Z

I think this is now ready. I added a few tests.

Copilot

Pull Request Overview

This PR introduces support for embedding static files from one Docker container into another during the build process. This enables scenarios like embedding a JavaScript frontend (built with Vite) into a Python backend server (FastAPI/Uvicorn).

Key changes:

New annotation system (ContainerFilesSourceAnnotation, ContainerFilesDestinationAnnotation) to mark resources that produce/consume static files
DockerfileBuildAnnotation.HasEntrypoint property to distinguish build-only containers from compute resources
Pipeline integration to ensure static file sources are built before their consumers
AddUvicornApp extension method for FastAPI/Uvicorn applications with automatic endpoint configuration

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`ResourceBuilderExtensions.cs`	Adds `PublishWithContainerFiles` extension method for configuring file copying between containers
`ResourceExtensions.cs`	Splits image build logic into `RequiresImageBuild` and `RequiresImageBuildAndPush` to handle build-only containers
`IResourceWithContainerFiles.cs`	New marker interface for resources that can produce container files
`DockerfileBuildAnnotation.cs`	Adds `HasEntrypoint` property to identify containers without entrypoints
`DockerfileStage.cs`	Renames parameter from `stage` to `from` for clarity in `CopyFrom` method
`ContainerFilesSourceAnnotation.cs`	Annotation marking the source path of files within a container
`ContainerFilesDestinationAnnotation.cs`	Annotation specifying where to copy files and from which source
`PythonAppResourceBuilderExtensions.cs`	Adds `AddUvicornApp` method and build pipeline logic for static file integration
`ViteAppResource.cs`	Implements `IResourceWithContainerFiles` interface
`NodeExtensions.cs`	Configures Vite apps as build-only containers with static file annotations
`AzureEnvironmentResource.cs`	Updates to use `RequiresImageBuild` instead of `RequiresImageBuildAndPush`
Test files	New tests and snapshots for the static files feature

src/Aspire.Hosting/ApplicationModel/IResourceWithContainerFiles.cs

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

src/Aspire.Hosting/ApplicationModel/IResourceWithContainerFiles.cs

eerhardt · 2025-10-24T00:04:01Z

src/Aspire.ProjectTemplates/templates/aspire-py-starter/13.0/Dockerfile

@@ -1,15 +1,4 @@
-# Stage 1: Build the Vite app


I love that the Dockerfile from the template moved to the test. 😆 Now you can see the diff in the dockerfile we generate vs what was laid down before.

…s.cs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

src/Aspire.Hosting/ResourceBuilderExtensions.cs

src/Aspire.Hosting.NodeJs/NodeExtensions.cs

src/Aspire.Hosting/ApplicationModel/ContainerFilesSourceAnnotation.cs

davidfowl · 2025-10-24T06:35:11Z

Attempting to deploy the template with this it seems like we're still trying to deploy the frontend even though we don't push it.

— Failed to deploy frontend: Deployment failed: ContainerAppOperationError: Failed to provision revision for container
app 'frontend'. Error details: The following field(s) are either invalid or missing. Field 'template.containers.frontend.image' is invalid with details:
'Invalid value: "envacrz6be3sjkvk7s2.azurecr.io/frontend:aspire-deploy-20251024061827": GET https:: MANIFEST_UNKNOWN: manifest tagged by
"aspire-deploy-20251024061827" is not found; map[Tag:aspire-deploy-20251024061827]';..

davidfowl · 2025-10-24T13:38:21Z

src/Aspire.Hosting/ApplicationModel/DistributedApplicationModelExtensions.cs

+            if (r.IsBuildOnlyContainer())
+            {
+                continue;
+            }


This feels like it's in the wrong place or this method has the wrong name.

In my opinion it isn't. A "build only container" (i.e. one that doesn't have an entrypoint) isn't a "Compute Resource". It can't stand alone. It doesn't have an entrypoint.

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

eerhardt requested review from davidfowl and mitchdenny October 21, 2025 22:35

eerhardt commented Oct 21, 2025

View reviewed changes

src/Aspire.Hosting.NodeJs/NodeAppResource.cs Outdated Show resolved Hide resolved

eerhardt commented Oct 21, 2025

View reviewed changes

src/Aspire.Hosting/ApplicationModel/StaticDockerFilesAnnotation.cs Outdated Show resolved Hide resolved

davidfowl reviewed Oct 21, 2025

View reviewed changes

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

davidfowl reviewed Oct 21, 2025

View reviewed changes

src/Aspire.Hosting/ApplicationModel/DistributedApplicationModelExtensions.cs Outdated Show resolved Hide resolved

davidfowl reviewed Oct 22, 2025

View reviewed changes

eerhardt commented Oct 22, 2025

View reviewed changes

This was referenced Oct 23, 2025

Add ViteApp and Npm Package Manager #12283

Merged

[WIP] Compute resources pipeline steps #12311

Closed

eerhardt force-pushed the RemoveDockerFileFromPyTemplate branch from 6e4a15d to 1030250 Compare October 23, 2025 18:47

eerhardt force-pushed the RemoveDockerFileFromPyTemplate branch from 1030250 to 69e92f1 Compare October 23, 2025 22:32

eerhardt added 2 commits October 23, 2025 18:41

Add a test and fix up code.

7eb2aa1

Add tests

425eb8a

eerhardt marked this pull request as ready for review October 24, 2025 00:00

eerhardt requested a review from captainsafia as a code owner October 24, 2025 00:00

Copilot AI review requested due to automatic review settings October 24, 2025 00:00

Copilot AI reviewed Oct 24, 2025

View reviewed changes

src/Aspire.Hosting/ApplicationModel/IResourceWithContainerFiles.cs Outdated Show resolved Hide resolved

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

eerhardt commented Oct 24, 2025

View reviewed changes

eerhardt and others added 2 commits October 23, 2025 19:05

Update src/Aspire.Hosting/ApplicationModel/IResourceWithContainerFile…

1a0e0a3

…s.cs

Update src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

ec125e7

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

eerhardt mentioned this pull request Oct 24, 2025

[New article]: Add docs for PublishWithContainerFiles dotnet/docs-aspire#5351

Open

davidfowl reviewed Oct 24, 2025

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Show resolved Hide resolved

davidfowl reviewed Oct 24, 2025

View reviewed changes

src/Aspire.Hosting.NodeJs/NodeExtensions.cs Outdated Show resolved Hide resolved

davidfowl reviewed Oct 24, 2025

View reviewed changes

src/Aspire.Hosting/ApplicationModel/ContainerFilesSourceAnnotation.cs Show resolved Hide resolved

eerhardt mentioned this pull request Oct 24, 2025

Decide if we want a UvicornAppResource deriving from PythonAppResource #12345

Open

Respond to PR feedback

e48fb38

davidfowl reviewed Oct 24, 2025

View reviewed changes

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

eerhardt added 2 commits October 24, 2025 09:26

Rename

cc7bc8f

Only add container files annotation during publish.

c22ba1c

davidfowl approved these changes Oct 24, 2025

View reviewed changes

davidfowl merged commit f5e40da into dotnet:main Oct 24, 2025
305 checks passed

dotnet-policy-service bot added this to the 13.0 milestone Oct 24, 2025

	// VS Code debug support - only applicable for Script and Module types
	if (entrypointType is EntrypointType.Script or EntrypointType.Module)

Add support for docker static files #12265

Add support for docker static files #12265

Uh oh!

Conversation

eerhardt commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eerhardt commented Oct 24, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidfowl commented Oct 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

eerhardt commented Oct 21, 2025 •

edited

Loading

github-actions bot commented Oct 21, 2025 •

edited

Loading