This guide documents the complete deployment of your existing Syed Portfolio API (.NET 8) from your Windows machine to Azure App Service using Docker and Azure Container Registry (ACR).

We will use the same architecture and configuration that we successfully implemented.

1. Deployment information

These are the actual names used in our deployment.

Important: We will retain .NET 8, as requested. No framework or EF Core version changes are included.

Part 1 – Prepare the Docker configuration

Step 1. Open your solution directory

Your project location:

D:\Syed\Project 2026\Portfolio Project\Syed Portfolio Project\Azure Portfolio

Open PowerShell:

cd "D:\Syed\Project 2026\Portfolio Project\Syed Portfolio Project\Azure Portfolio"

Your solution structure:

Azure Portfolio
│
├── Syed.PortfolioPlatform.sln
│
├── Syed.PortfolioPlatform.API
│   ├── Controllers
│   ├── Program.cs
│   └── Syed.PortfolioPlatform.API.csproj
│
├── Syed.PortfolioPlatform.Application
│
├── Syed.PortfolioPlatform.Domain
│
├── Syed.PortfolioPlatform.Infrastructure
│
├── Syed.PortfolioPlatform.Functions.Notifications
│
└── Syed.PortfolioPlatform.Web

We will create the Dockerfile in the solution root, not inside the API project.

Step 2. Create Dockerfile

Create a file named:

Dockerfile

Location:

Azure Portfolio\Dockerfile

Add the following content:

# Stage 1: Build the application
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

WORKDIR /src

# Copy source code
COPY . .

# Restore dependencies
RUN dotnet restore "Syed.PortfolioPlatform.API/Syed.PortfolioPlatform.API.csproj"

# Publish the API
RUN dotnet publish "Syed.PortfolioPlatform.API/Syed.PortfolioPlatform.API.csproj" \
    -c Release \
    -o /app/publish \
    --no-restore

# Stage 2: Runtime image
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final

WORKDIR /app

# Application listening port
ENV ASPNETCORE_HTTP_PORTS=8080

EXPOSE 8080

# Copy published application
COPY --from=build /app/publish .

# Start API
ENTRYPOINT ["dotnet", "Syed.PortfolioPlatform.API.dll"]

Understand the Dockerfile

We are using a multi-stage Docker build.

Source Code
     |
     ▼
.NET 8 SDK Image
     |
     ▼
Restore NuGet Packages
     |
     ▼
Publish API
     |
     ▼
.NET 8 ASP.NET Runtime Image
     |
     ▼
Final Docker Image

The final runtime image doesn't contain the complete .NET SDK.

Step 3. Create .dockerignore

Create another file:

.dockerignore

Add:

**/bin/
**/obj/
**/.vs/
.vs/
.vscode/
.git/
.github/
**/TestResults/
**/*.user
**/*.suo
.env
.env.*
**/secrets*.json

Syed.PortfolioPlatform.Web/
Syed.PortfolioPlatform.Functions.Notifications/

Why do we need it?

Docker uses the build context to determine which files to send to the Docker engine.

We don't need to include:

• Compiled files (bin, obj).

• Visual Studio temporary files.

• Git repository information.

• Environment files containing secrets.

• Unrelated Web and Functions projects.

This reduces the build context and prevents unnecessary files from being copied into the build environment.

Step 4. Verify the Docker configuration

Execute:

Get-Content .\Dockerfile
Get-Content .\.dockerignore

Our solution root now contains:

Azure Portfolio
│
├── Dockerfile
├── .dockerignore
├── Syed.PortfolioPlatform.sln
│
├── Syed.PortfolioPlatform.API
├── Syed.PortfolioPlatform.Application
├── Syed.PortfolioPlatform.Domain
└── Syed.PortfolioPlatform.Infrastructure

Part 2 – Build and test the Docker image locally

Step 5. Build Docker image

Make sure Docker Desktop is running.

Execute:

docker build -t syed-portfolio-api:v1 .

Explanation:

Verify:

docker images syed-portfolio-api

Expected:

REPOSITORY             TAG
syed-portfolio-api     v1

Step 6. Run the Docker container locally

Initially, we tried running the container using default settings and encountered a Key Vault authentication error.

This happened because your Program.cs loads Azure Key Vault in Production mode.

For local Docker testing, we use Development mode.

Your existing code:

if (builder.Environment.IsProduction())
{
    var vaultUri = builder.Configuration["KeyVault:VaultUri"];

    if (!string.IsNullOrEmpty(vaultUri))
    {
        builder.Configuration.AddAzureKeyVault(
            new Uri(vaultUri),
            new DefaultAzureCredential());
    }
}

When running locally:

ASPNETCORE_ENVIRONMENT=Development

The application skips Azure Key Vault initialization.

6.1 Prepare local SQL Server

Our local API uses SQL Server running directly on Windows.

We configured:

• SQL Server default instance: MSSQLSERVER.

• TCP/IP: Enabled.

• Static port: 1433.

• Authentication: SQL Server and Windows Authentication.

• SQL login: portfolio_docker_user.

• Database: ServerDB_Bak_121026.

The important distinction:

Windows:
Server=.

means your local Windows SQL Server.

Inside Docker:

Server=.

means the container itself.

Therefore, we use:

host.docker.internal,1433

This allows a Docker Desktop container to connect to services on your Windows host.

6.2 Run container with database connection

Use this PowerShell script.

# Get password securely
$securePassword = Read-Host "SQL Password" -AsSecureString

$sqlPassword = [Net.NetworkCredential]::new(
    "",
    $securePassword
).Password

# Create connection string
$builder = [System.Data.Common.DbConnectionStringBuilder]::new()

$builder["Server"] = "host.docker.internal,1433"
$builder["Database"] = "ServerDB_Bak_121026"
$builder["User ID"] = "portfolio_docker_user"
$builder["Password"] = $sqlPassword
$builder["Encrypt"] = "True"
$builder["TrustServerCertificate"] = "True"

# Run Docker container
docker run -d `
    --name syed-portfolio-api-local `
    -e ASPNETCORE_ENVIRONMENT=Development `
    -e "ConnectionStrings__DefaultConnection=$($builder.ConnectionString)" `
    -p 8080:8080 `
    syed-portfolio-api:v1

# Clear local variables
Remove-Variable sqlPassword, securePassword, builder

Security note: This is for local practice. Docker environment variables can be viewed by users with Docker access through container inspection. Don't use this method to store production secrets.

6.3 Understand port mapping

-p 8080:8080

The first port is the Windows host port.

The second port is the container port.

Windows Machine
    |
    | http://localhost:8080
    |
    ▼
Docker Container
    |
    | Port 8080
    |
    ▼
ASP.NET Core API

6.4 Verify the running container

Execute:

docker ps

Then:

docker logs syed-portfolio-api-local

Expected application log:

Starting DB Migration...
DB Migration completed

6.5 Test locally

Open:

http://localhost:8080/swagger

We successfully tested Swagger and our API endpoints.

You can also test:

http://localhost:8080/api/articles/categories

Part 3 – Prepare a traceable Docker image

Step 7. Commit Docker configuration to Git

We used Git to ensure that the Docker image can be traced back to a specific source-code revision.

Check Git:

git status --short

Stage the Docker files:

git add Dockerfile .dockerignore

Review:

git diff --cached --check
git diff --cached

Commit:

git commit -m "Add Docker build configuration"

Verify:

git log -1 --oneline

Our final commit SHA:

4c39725130e3

Check the working directory:

git status --short

Expected: No output, indicating a clean working tree.

Step 8. Build a Git-based Docker image

Instead of using a generic tag like latest, we use a tag derived from the Git commit SHA.

This provides traceability.

Execute:

$gitSha = (git rev-parse --short=12 HEAD).Trim()

$imageTag = "sha-$gitSha"

$localImage = "syed-portfolio-api:$imageTag"

Write-Host $localImage

Expected:

syed-portfolio-api:sha-4c39725130e3

Now build:

docker build --pull -t $localImage .

Verify:

docker images syed-portfolio-api

Our image version is now:

syed-portfolio-api:sha-4c39725130e3

A future source-code commit will produce a different tag.

Part 4 – Create Azure Container Registry

Step 9. Create ACR in Azure Portal

Open <Link url="https://portal.azure.com/" title="Azure Portal"/>.

Follow:

1. Search for Container registries.

2. Select Create.

3. Configure the Basics tab.

For this exercise, a Basic registry is generally sufficient for a small image repository. Choose a higher tier when your throughput, storage or advanced registry requirements justify it.

9.1 Review advanced settings

Our ACR uses:

RBAC Registry Permissions

Retain this permission mode.

This is important because we will use the standard AcrPull role for App Service.

4. Select Review + create.

5. Select Create.

6. Wait for successful deployment.

7. Select Go to resource.

9.2 Verify ACR

On the Overview page:

Part 5 – Push Docker image to ACR

This part requires Docker and Azure CLI commands on your development machine.

The Azure resources themselves were created and configured through the Azure Portal.

The Portal doesn't directly take a local Docker image from your D: drive and push it to ACR. Docker must perform that upload.

Step 10. Authenticate Docker with Azure

Check Azure CLI:

az --version

Check your subscription:

az account show --output table

Log in to ACR:

az acr login --name jntechportfolioacr

Expected:

Login Succeeded

Your user identity must have permission to push images to this registry, typically through the AcrPush role under the current RBAC permission mode.

Step 11. Tag the Docker image

Get the ACR login server:

$loginServer = "jntechportfolioacr.azurecr.io"

Generate the image reference:

$gitSha = (git rev-parse --short=12 HEAD).Trim()

$imageTag = "sha-$gitSha"

$localImage = "syed-portfolio-api:$imageTag"

$acrImage = "$loginServer/syed-portfolio-api:$imageTag"

Tag the image:

docker tag $localImage $acrImage

Verify:

docker image inspect $acrImage --format '{{.Id}}'

Compare it with the local image:

docker image inspect $localImage --format '{{.Id}}'

Both should display the same image ID.

Our ACR image reference:

jntechportfolioacr.azurecr.io/syed-portfolio-api:sha-4c39725130e3

Step 12. Push image to ACR

Execute:

docker push $acrImage

Docker will upload the image layers and manifest.

Expected result:

sha-4c39725130e3: digest: sha256:xxxxx size: xxxx

We previously encountered:

authentication required

The solution was to authenticate again:

az acr login --name jntechportfolioacr

Then retry:

docker push $acrImage

Step 13. Verify image in Azure Portal

Open:

Azure Portal → Container registries → jntechportfolioacr.

Navigate to Repositories.

Select:

syed-portfolio-api

You should find:

sha-4c39725130e3

You can also inspect the image manifest digest.

<badge color="success">Docker image successfully stored in ACR</badge>

Part 6 – Create Azure App Service

Step 14. Create App Service

In Azure Portal:

1. Search for App Services.

2. Select Create → Web App.

14.1 Basics tab

Use the following settings:

Our F1 plan is being used for learning and testing, not production.

14.2 Container tab

Configure:

The container must expose the same HTTP port that the ASP.NET Core application listens on.

14.3 Create Web App

1. Select Review + create.

2. Verify all settings.

3. Select Create.

4. Wait for deployment.

5. Select Go to resource.

Part 7 – Configure Managed Identity

Managed Identity allows Azure services to authenticate without storing passwords or credentials in the application.

Step 15. Enable System-Assigned Managed Identity

In Azure Portal:

1. Open App Service: jntech-portfolio-api.

2. Navigate to Settings → Identity.

3. Select System assigned.

4. Change Status to On.

5. Select Save.

6. Confirm the operation.

Azure generates an Object/Principal ID.

This identity represents your App Service.

Step 16. Grant ACR image-pull permission

We configured our ACR using RBAC Registry Permissions.

Therefore, assign the standard AcrPull role.

In Azure Portal:

1. Open jntechportfolioacr.

2. Select Access control (IAM).

3. Select Add → Add role assignment.

4. Search for AcrPull.

5. Select AcrPull.

6. Click Next.

Members tab

Configure:

7. Click Select.

8. Click Review + assign.

9. Complete the assignment.

Architecture:

App Service
     |
     ▼
System-Assigned Managed Identity
     |
     ▼
Microsoft Entra ID
     |
     ▼
AcrPull Permission
     |
     ▼
Azure Container Registry

Important correction for our deployment: We initially explored Container Registry Repository Reader because of the ABAC permission model. However, your actual registry uses RBAC Registry Permissions. The applicable role is AcrPull. Don't use the earlier conditional Repository Reader assignment for this deployment.

Step 17. Configure App Service container authentication

Open:

App Service → jntech-portfolio-api → Deployment → Deployment Center → Containers.

Select the main container to edit.

Configure:

Select Apply or Save.

Now Azure App Service can authenticate to ACR using its Managed Identity.

Part 8 – Configure Azure Key Vault

Your API uses Azure Key Vault to retrieve application secrets during Production startup.

Your existing implementation:

if (builder.Environment.IsProduction())
{
    var vaultUri = builder.Configuration["KeyVault:VaultUri"];

    if (!string.IsNullOrEmpty(vaultUri))
    {
        builder.Configuration.AddAzureKeyVault(
            new Uri(vaultUri),
            new DefaultAzureCredential());
    }
}

We must configure Key Vault access for the same App Service Managed Identity.

Step 18. Verify Key Vault permission model

In Azure Portal:

1. Search for Key vaults.

2. Open your Portfolio Key Vault.

3. Navigate to Settings → Access configuration.

4. Verify the permission model.

Our existing configuration:

Vault access policy

Do not change it.

Step 19. Grant Key Vault permissions

Open:

Key Vault → Access policies → Create.

Permissions tab

Select:

Why Get and List?

Your application uses the Azure Key Vault configuration provider, which must enumerate and retrieve secrets.

Principal tab

1. Click Select principal.

2. Search for jntech-portfolio-api.

3. Select the System-Assigned Managed Identity.

4. Click Select.

5. Continue and create the access policy.

Expected:

Principal:
jntech-portfolio-api

Secret permissions:
Get
List

Step 20. Verify Key Vault secrets

Navigate to:

Key Vault → Objects → Secrets.

Verify these secret names:

The double hyphen -- is used as the hierarchy separator by the Azure Key Vault configuration provider.

Important: Your production connection string must point to Azure SQL Database, not your Windows SQL Server.

Don't use your local connection string:

Server=.;
Trusted_Connection=True;

The actual secret values must remain inside Key Vault. Never place database credentials in your Dockerfile or Git repository.

Part 9 – Configure App Service environment variables

Now we will configure three important environment variables.

Step 21. Open Environment variables

In Azure Portal:

1. Open jntech-portfolio-api.

2. Navigate to Settings → Environment variables.

3. Select App settings.

4. Click + Add.

Add the following three settings.

Example:

WEBSITES_PORT = 8080

ASPNETCORE_ENVIRONMENT = Production

KeyVault__VaultUri =
https://your-keyvault-name.vault.azure.net/

The exact Key Vault URI should be copied from your Key Vault Overview page.

Why WEBSITES_PORT?

Your Dockerfile contains:

ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080

By default, Azure App Service assumes custom containers listen on port 80. Setting WEBSITES_PORT=8080 tells App Service which internal HTTP port to route to. <Cite refs={["turn289939search0","turn224251search3"]}/>

Why double underscore?

ASP.NET Core converts:

KeyVault__VaultUri

into:

KeyVault:VaultUri

This matches your existing Program.cs configuration.

After adding all three settings:

1. Click Apply.

2. Click Save.

3. Confirm the App Service restart.

Part 10 – Verify deployment and application startup

Step 22. Verify container deployment

Open:

App Service → Deployment Center → Containers.

Verify these details:

Step 23. Enable application logging

Open:

App Service → Monitoring → App Service logs.

Configure:

Save the configuration.

Then navigate to:

Monitoring → Log stream

This displays live log entries when the application writes them to the container console.

Step 24. Examine Docker container logs through Kudu

We used this approach to troubleshoot our actual deployment.

In Azure Portal:

1. Open App Service.

2. Navigate to Development Tools → Advanced Tools.

3. Select Go.

4. Open Kudu Dashboard.

5. Select Browse Log Files.

6. Open /home/LogFiles/.

Find:

*_default_docker.log

Don't confuse it with:

*_default_scm_docker.log

The second file contains Kudu/SCM management container logs, not your Portfolio API application logs.

Our actual API container log showed:

Starting DB Migration...
DB Migration completed

This confirmed that database migration completed successfully.

Microsoft documents the App Service container log locations and Kudu access procedure in its custom container diagnostics documentation. <Cite refs={["turn224251search3","turn224251search5"]}/>

Step 25. Verify API through the browser

Open:

App Service → Overview.

Copy the Default Domain.

Example:

https://jntech-portfolio-api.azurewebsites.net

Test your API:

https://jntech-portfolio-api.azurewebsites.net/api/articles/categories

<badge color="success">Successful deployment</badge>

In our deployment, this endpoint returned category data successfully.

You can also test:

• Article listing.

• Category listing.

• Tag listing.

• Other public API endpoints.

Remember, Swagger may be disabled in Production. Successful API responses are a better deployment check than Swagger availability alone.

Part 11 – Deployment maintenance and best practices

The initial deployment is completed. The following practices should be followed for future releases.

Step 26. Deploy a new version

Whenever you change your Portfolio API source code:

1. Commit source code

git add .
git commit -m "Update portfolio API"

2. Generate a new image tag

$gitSha = (git rev-parse --short=12 HEAD).Trim()

$imageTag = "sha-$gitSha"

$localImage = "syed-portfolio-api:$imageTag"

3. Build Docker image

docker build --pull -t $localImage .

4. Tag for ACR

$loginServer = "jntechportfolioacr.azurecr.io"

$acrImage = "$loginServer/syed-portfolio-api:$imageTag"

docker tag $localImage $acrImage

5. Authenticate and push

az acr login --name jntechportfolioacr

docker push $acrImage

6. Update App Service

In Azure Portal:

App Service → Deployment Center → Containers.

Edit the image tag from the previous version to the new version and save.

Azure App Service will pull the new image and restart the application.

7. Verify

Test your API URL and inspect container logs.

Step 27. Rollback

Suppose your new deployment has a problem.

Your ACR might contain:

syed-portfolio-api
    |
    ├── sha-previous-version
    |
    └── sha-new-version

To roll back:

1. Open Azure App Service.

2. Navigate to Deployment Center → Containers.

3. Edit the container.

4. Change the image tag to the previously successful version.

5. Save and restart.

6. Test the API.

This is why Git-based image versioning is useful.

Step 28. Remove unnecessary permissions

For our current configuration:

• Keep AcrPull assigned to jntech-portfolio-api.

• Keep the Key Vault Get and List access policy.

• Remove the earlier conditional Container Registry Repository Reader assignment if it still exists and is no longer needed.

Do not enable ACR administrator credentials just to simplify authentication.

Part 12 – What about Docker Compose?

Docker Compose is not required in this deployment.

Your current architecture contains one API container.

Portfolio API
     |
     ▼
Dockerfile
     |
     ▼
Docker Image
     |
     ▼
ACR
     |
     ▼
Azure App Service

Docker Compose is useful when you want to start multiple related containers together during local development.

For example:

docker-compose.yml
       |
       ├── Portfolio API
       |
       ├── SQL Server
       |
       └── Redis

You can start the entire local environment using:

docker compose up

For this single-container App Service deployment, the Dockerfile is sufficient.

Part 13 – Important production considerations

Before using this architecture for a real public application, consider the following.

Important: The F1 plan is also suitable for this learning exercise, not a production SLA-backed public service.

Official Microsoft documentation

For future reference:

1. Configure Custom Containers in Azure App Service

2. Azure Container Registry documentation

3. Managed Identity in App Service

4. Azure Key Vault Access Policies

5. .NET Release and Support Policy