Subjective.Aspire.Hosting.Garage 0.1.0-preview.6

Garage for Aspire

Run Garage S3 object storage in an Aspire application. The integration starts Garage, provisions buckets, and provides connection strings to your services.

Requires .NET 10, Aspire 13.5.3 or later, and a container runtime.

Usage

Reference the Subjective.Aspire.Hosting.Garage package in your AppHost:

using Aspire.Hosting;

var garage = builder.AddGarage("storage").WithDataVolume();
var photos = garage.AddBucket("photos", "place-photos");

builder.AddProject<Projects.Api>("api")
    .WithReference(photos)
    .WaitFor(garage);

The API receives ConnectionStrings:photos with the S3 endpoint, credentials, region, bucket name, and path-style setting. The same resource graph supports local development and Docker Compose publication.

WaitFor(garage) waits for Garage health and successful provisioning of the declared buckets and credentials. You can also use WaitFor(photos) to wait on a bucket. Garage starts first so the provisioner can use its admin API. Consumers do not need to reference the provisioner directly.

Configuration

Pass GarageResourceOptions from the Garage.Hosting namespace to AddGarage to configure the region, capacity, custom TOML (ConfigPath or ConfigContents), and provisioner image. Standard Aspire methods configure endpoints, images, and volumes.

Use a named endpoint to choose a host port. The container's S3 port remains 3900:

garage.WithEndpoint("s3", endpoint => endpoint.Port = 9000);

The other endpoint names are admin and rpc. Port controls the host port; TargetPort must match the service's listener inside the container. Changing endpoint metadata does not rewrite custom TOML. Keep the default container ports and data paths unless you also configure Garage and its mounts to match.

WithDataVolume uses /var/lib/garage inside the container. To use a host directory instead, call WithBindMount("./garage-data", GarageResource.DataPath).

Credentials are generated by default; AddGarage also accepts explicit secret parameters. Retain the credentials and data volume across deployments. All declared buckets share the application key.

The default configuration runs one node with replication factor one. Set ProvisionSingleNodeLayout = false to manage the layout yourself. Custom TOML must match the configured region, endpoints, and data paths.

Development

• src/Hosting — Aspire resources and builder extensions.
• src/Provisioner — bucket and key setup container.
• tests/Hosting.Tests — integration configuration tests.
• samples — AppHost with an S3 upload/download check.

Run dotnet test to test the library, or aspire start --apphost samples/AppHost/AppHost.csproj to run the sample.

Releases publish preview packages to NuGet.org and GitHub Releases, alongside the matching provisioner container. The release workflow uses NuGet Trusted Publishing with the Subjective account and a policy bound to release.yml. The policy must allow the package ID Subjective.Aspire.Hosting.Garage.

The package and assembly name identify the independent publisher. Builder extensions use Aspire.Hosting and resource types use Aspire.Hosting.ApplicationModel, following Aspire's custom hosting integration conventions. Options and implementation helpers use Garage.Hosting. To migrate from the earlier GitHub packages, replace the package reference and update any using Aspire.Hosting.Garage; imports to these namespaces.