Skip to content

docs: enhance deployment guide with prerequisites and common pitfalls #248

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adamint merged 1 commit into from
Jan 22, 2026
Merged

docs: enhance deployment guide with prerequisites and common pitfalls #248

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 44 additions & 33 deletions src/frontend/src/content/docs/get-started/deploy-first-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,8 @@ The React (Vite) & FastAPI starter template consists of two resources that are d

## Prerequisites

Depending on where you want to deploy your Aspire app, ensure you have the following prerequisites installed and configured:

<Tabs syncKey="deploy-target">
<TabItem id="docker-compose" label="Docker Compose">
<div class="sl-flex sl-gap-4 sl-items-center sl-mb-4">
Expand Down Expand Up @@ -128,17 +130,18 @@ In the root directory of your Aspire solution that you created in the previous q
<LearnMore>
Learn more about the `aspire add` command in the [reference docs](/reference/cli/commands/aspire-add/).
</LearnMore>

</Tabs>

## Update your AppHost

In the AppHost, be sure to add the appropriate environment API.
In the AppHost, chain a call to the appropriate environment API method to configure the deployment environment for your target.

<Tabs syncKey="deploy-target">
<TabItem id="docker-compose" label="Docker Compose">

<Pivot id="csharp">
```csharp title="C# — AppHost.cs project-based orchestrator" {3-4} ".WithExternalHttpEndpoints()"
```csharp title="C# — AppHost.cs project-based orchestrator" {3-4}
var builder = DistributedApplication.CreateBuilder(args);

// Add the following line to configure the Docker Compose environment
Expand All @@ -157,7 +160,7 @@ In the AppHost, be sure to add the appropriate environment API.
```
</Pivot>
<Pivot id="python">
```csharp title="C# — apphost.cs file-based orchestrator" {4,8-9} ".WithExternalHttpEndpoints()"
```csharp title="C# — apphost.cs file-based orchestrator" {8-9}
#:sdk [email protected]
#:package [email protected]
#:package [email protected]
Expand Down Expand Up @@ -190,7 +193,7 @@ In the AppHost, be sure to add the appropriate environment API.
<TabItem id="azure" label="Azure">

<Pivot id="csharp">
```csharp title="C# — AppHost.cs project-based orchestrator" {3-4} ".WithExternalHttpEndpoints()"
```csharp title="C# — AppHost.cs project-based orchestrator" {3-4}
var builder = DistributedApplication.CreateBuilder(args);

// Add the following line to configure the Azure App Container environment
Expand All @@ -209,7 +212,7 @@ In the AppHost, be sure to add the appropriate environment API.
```
</Pivot>
<Pivot id="python">
```csharp title="C# — apphost.cs file-based orchestrator" {4,8-9} ".WithExternalHttpEndpoints()"
```csharp title="C# — apphost.cs file-based orchestrator" {8-9}
#:sdk [email protected]
#:package [email protected]
#:package [email protected]
Expand Down Expand Up @@ -249,37 +252,17 @@ After installing a new deployment package, you can run `aspire do diagnostics` i

Now that you've added the deployment package and updated your AppHost, you can deploy your Aspire app.

```bash title="Aspire CLI — Deploy your app"
aspire deploy
```

When you call `aspire deploy`, the Aspire CLI builds the container images for your resources, pushes them to the target environment (if applicable), and deploys the resources according to the configuration in your AppHost.

<Aside type="note" title="Common pitfall..." icon="seti:todo">
If you call `aspire deploy` and you see output similar to the following, be sure that you've actually [updated your AppHost](#update-your-apphost) to include the appropriate environment API for your target. This output indicates that there are no deploy steps configured for your target environment.

```bash title="Aspire CLI - Empty deployment output"
14:17:26 (pipeline execution) → Starting pipeline execution...
14:17:26 (deploy) → Starting deploy...
14:17:26 (deploy) ✓ deploy completed successfully
14:17:26 (pipeline execution) ✓ Completed successfully
------------------------------------------------------------
✓ 2/2 steps succeeded • Total time: 0.0s

Steps Summary:
0.0 s ✓ pipeline execution
0.0 s ✓ deploy

✓ PIPELINE SUCCEEDED
------------------------------------------------------------
```
</Aside>

<Tabs syncKey="deploy-target">

<TabItem id="docker-compose" label="Docker Compose">

Deploying to Docker Compose builds the container images and starts the services locally using Docker Compose. Consider the following example output:
Deploying to Docker Compose builds the container images and starts the services locally using Docker Compose.

```bash title="Aspire CLI — Deploy your app"
aspire deploy
```

Consider the following example output:

<Pivot id="csharp">

Expand Down Expand Up @@ -437,7 +420,13 @@ Steps Summary:
- `Azure__Location`: Azure region (for example, eastus).
- `Azure__ResourceGroup`: Resource group name to create or reuse.

Deploying to Azure App Containers builds the container images and deploys the services to Azure App Containers. Consider the following example output:
Deploying to Azure App Containers builds the container images and deploys the services to Azure App Containers.

```bash title="Aspire CLI — Deploy your app"
aspire deploy
```

Consider the following example output:

<Pivot id="csharp">

Expand Down Expand Up @@ -648,6 +637,28 @@ Steps Summary:
</TabItem>
</Tabs>

When you call `aspire deploy`, the Aspire CLI builds the container images for your resources, pushes them to the target environment (if applicable), and deploys the resources according to the configuration in your AppHost.

<Aside type="note" title="Common pitfall..." icon="seti:todo">
If you call `aspire deploy` and you see output similar to the following, be sure that you've actually [updated your AppHost](#update-your-apphost) to include the appropriate environment API for your target. This output indicates that there are no deploy steps configured for your target environment.

```bash title="Aspire CLI - Empty deployment output"
14:17:26 (pipeline execution) → Starting pipeline execution...
14:17:26 (deploy) → Starting deploy...
14:17:26 (deploy) ✓ deploy completed successfully
14:17:26 (pipeline execution) ✓ Completed successfully
------------------------------------------------------------
✓ 2/2 steps succeeded • Total time: 0.0s

Steps Summary:
0.0 s ✓ pipeline execution
0.0 s ✓ deploy

✓ PIPELINE SUCCEEDED
------------------------------------------------------------
```
</Aside>

<LearnMore>
Additional information about this command can be found in the [`aspire deploy`](/reference/cli/commands/aspire-deploy/) reference docs.
</LearnMore>
Expand Down
Loading