Skip to content

Deployment and running guide

This page describes two ways to run the Cargonerds solution:

  1. Local development using .NET Aspire – great for debugging and development on your own machine.
  2. Deployment to Azure Container Apps – using the provided PowerShell script and the Azure Developer CLI (azd).

Both approaches rely on the declarative model defined in Cargonerds.AppHost. For an overview of how the AppHost orchestrates services and resources, see the architecture and the Cargonerds module documentation.

Prerequisites

To run the system locally or deploy it to the cloud you will need the following tools installed:

  • .NET 8 SDK – to build and run the projects.
  • Docker – for running SQL Server, Redis and RabbitMQ locally when using .NET Aspire. If Docker is not installed, Aspire will attempt to connect to local services; however the recommended setup is to run with Docker. On Windows you can use the Docker Desktop.
  • Node.js and npm – if you plan to use the optional NPM front‑end (not included in this repository), you will need Node.js installed.
  • Azure CLI and Azure Developer CLI (azd) – required for deployment to Azure Container Apps. You also need an Azure account with permission to create resources in a subscription.
  • PowerShell 7 – the deployment script is written in PowerShell and uses the PS‑Menu module for interactive menus.

Running locally with Aspire

To start all services locally, run the Cargonerds.AppHost project. This project uses .NET Aspire to spin up infrastructure and wire everything together【798564215460282†L254-L259】. Perform the following steps:

  1. Ensure that Docker is running on your machine and that ports 1433 (SQL Server), 6379 (Redis) and 5672 (RabbitMQ) are free.
  2. Open a terminal and navigate to the AppHost directory:
cd src/Cargonerds.AppHost
dotnet run
  1. The first time you run the project, Aspire will pull Docker images for SQL Server, Redis and RabbitMQ and create containers for them. It will then start the DbMigrator (to apply migrations and seed data), AuthServer, HttpApi.Host, Web.Public, Blazor and the optional NPM app. The Aspire dashboard will open in your default browser.
  2. Use the dashboard to discover the URLs of each service. By default they are mapped to sequential ports starting at 5000 for AuthServer, 6000 for HttpApi.Host, 7000 for Web.Public and 8000 for Blazor, but this may vary. You can also view logs, metrics and dependencies in the dashboard.
  3. When you change the code or add migrations, stop the AppHost (Ctrl+C), run the DbMigrator manually (cd ../Cargonerds.DbMigrator && dotnet run) to apply migrations and seed data, and then start the AppHost again.

Environment variables

The AppHost configures most settings automatically via extension methods such as WithAbpSelfUrl and WithAbpRedisReference. If you need to override connection strings or URLs, you can use the standard .NET configuration hierarchy (environment variables, appsettings.json, appsettings.Development.json). For example, to use an existing SQL Server instance instead of the Docker container, set the ConnectionStrings__Default environment variable before running the AppHost.

Deploying to Azure Container Apps

The repository includes a PowerShell script, .scripts/DeployToAzureContainerApps.ps1, which automates deployment to Azure Container Apps and configures custom DNS entries and TLS certificates. The script uses the Azure Developer CLI (azd) under the hood. Before running the script ensure that you are signed in to Azure (az login) and that you have rights to create resources in your subscription and manage DNS records in the cargonerds.dev zone.

Running the script

  1. Install the PS‑Menu module if prompted. The script will automatically install it for the current user if not found.
  2. Open a PowerShell prompt and navigate to the .scripts folder in the repository root:
cd .\scripts
.\DeployToAzureContainerApps.ps1

  1. When the script starts it displays a welcome message and asks for an environment name. You have three options:

  2. Use the current Git branch name – the script sanitises the branch name (replacing non‑alphanumeric characters with hyphens) and uses it as the environment name.

  3. Use the value of the CARGONERDS_APP_ENV_NAME environment variable – if set, this overrides the branch name.
  4. Enter a custom name – you can type your own environment name.

The environment name becomes part of the resource group name (rg-ABP-<env>), the Azure Developer CLI environment (ABP-<env>) and the DNS subdomain (<env>.cargonerds.dev). 4. The script calls azd up inside the Cargonerds.AppHost project folder. This command provisions an Azure Container Apps environment, creates a separate container app for each service (AuthServer, HttpApi.Host, Web.Public, Blazor, DbMigrator) and deploys your code. It also creates Azure resources for SQL (Azure SQL), Redis (Azure Cache for Redis) and RabbitMQ (Azure Service Bus) and configures the services to connect to them. 5. After the deployment finishes, the script retrieves the list of container apps and calls SetupDnsAndCertificates.ps1. This second script performs the following tasks for each externally accessible container app:

  • Creates a TXT record (asuid.<service>.<env>) in the DNS zone to validate domain ownership.
  • Creates a CNAME record mapping <service>.<env>.cargonerds.dev to the default domain of the container app.
  • Binds the custom domain and automatically provisions a TLS certificate via Azure Container Apps. After the certificate is issued the TXT record is removed.
  • Once all domains are set up, the script prints instructions for accessing the services. Each service will be available at https://<service>.<env>.cargonerds.dev with a valid TLS certificate. For example, the AuthServer might be available at https://auth.<env>.cargonerds.dev and the API at https://api.<env>.cargonerds.dev.
  • The script then pauses and waits for your input. Type exit to keep the environment running or destroy to tear it down. If you choose to destroy the environment, the script executes azd down to delete the Container Apps environment and runs CleanupDnsEntries.ps1 to remove the CNAME records from DNS.

Customising deployment

  • DNS zone and resource group – by default the scripts use the cargonerds.dev DNS zone and the resource group rg-cargonerds-applications-core-infrastructure to manage DNS records. If you need to use a different zone, modify the variables at the top of DeployToAzureContainerApps.ps1 and SetupDnsAndCertificates.ps1.
  • Azure region – the script sets AZURE_LOCATION to germanywestcentral. You can override this environment variable before running azd up to deploy to a different region.
  • Cleaning up – when destroying an environment, the script only removes CNAME records created by the deployment. If you have added other DNS records, remove them manually.

Further reading

By following the instructions above you can run the Cargonerds application locally for development and testing and deploy it to Azure for production or staging environments. If you run into issues during deployment, consult the logs printed by the scripts and the Azure portal for more details.