Skip to main content

​
Overview

Before running the AspNetRun Microservices application, ensure you have the following tools installed on your development machine. This guide provides installation instructions for Windows, macOS, and Linux.

​
Required Software

All three tools are required to run the application with Docker Compose. For development, you’ll need additional tools listed in the optional section.

​
.NET 8 SDK

The application is built on .NET 8, which includes the latest features of C# 12 and ASP.NET Core 8.
1

Download .NET 8 SDK

Download the SDK from the official Microsoft website:Windows: Download .NET 8 SDK for Windows
macOS: Download .NET 8 SDK for macOS
Linux: Download .NET 8 SDK for Linux
Download the SDK, not just the Runtime. The SDK includes everything needed to build and run .NET applications.
2

Install the SDK

Run the installer and follow the prompts. The installation typically takes 2-3 minutes.For Linux, use your distribution’s package manager:
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0
3

Verify Installation

Open a terminal or command prompt and verify the installation:
dotnet --version
Expected output: 8.0.x (where x is the latest patch version)Check installed SDKs:
dotnet --list-sdks
You should see .NET 8.0.x listed.

​
Docker Desktop

Docker Desktop provides containerization for all microservices and infrastructure components.
1

Download Docker Desktop

Download Docker Desktop for your operating system:Windows: Download Docker Desktop for Windows
macOS: Download Docker Desktop for Mac
Linux: Download Docker Desktop for Linux or use Docker Engine
Windows users must enable WSL 2 (Windows Subsystem for Linux) before installing Docker Desktop. The installer will guide you through this process.
2

Install Docker Desktop

Run the installer and follow the installation wizard:
  1. Accept the license agreement
  2. Choose installation options (use WSL 2 on Windows)
  3. Complete the installation
  4. Restart your computer if prompted
For Linux without Docker Desktop, install Docker Engine:
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
Log out and back in for group changes to take effect.
3

Configure Docker Desktop

After installation, configure Docker Desktop for optimal performance:
  1. Open Docker Desktop
  2. Go to Settings → Resources
  3. Allocate sufficient resources:
    • Memory: Minimum 4 GB (recommended: 8 GB)
    • CPU: Minimum 2 cores (recommended: 4 cores)
    • Disk: 20 GB available space
    • Swap: 1 GB (Windows/Mac only)
The AspNetRun application runs 6 microservices and 4 databases simultaneously. Insufficient resources will cause containers to fail or perform poorly.
  1. Click Apply & Restart
4

Verify Installation

Open a terminal and verify Docker is running:
docker --version
Expected output: Docker version 24.x.x or higherVerify Docker Compose:
docker-compose --version
Expected output: Docker Compose version v2.x.x or higherTest Docker is working:
docker run hello-world
You should see a welcome message from Docker.

​
Visual Studio 2022 (Optional)

Visual Studio 2022 provides the best development experience for .NET microservices, with IntelliSense, debugging, and Docker integration.
1

Download Visual Studio 2022

Download the Community (free) or Professional edition:Download Visual Studio 2022
Visual Studio Community is free for individual developers, open-source projects, academic research, education, and small professional teams.
2

Select Workloads

During installation, select these workloads:
  • ASP.NET and web development - Required for ASP.NET Core development
  • .NET desktop development - Optional, for desktop tools
  • Azure development - Optional, for cloud deployment
  • Container development - Enables Docker integration
Individual components to add:
  • .NET 8.0 Runtime
  • Docker Desktop integration
  • Git for Windows (if not already installed)
3

Verify Installation

Launch Visual Studio 2022 and check the version:
  1. Go to Help → About Microsoft Visual Studio
  2. Verify version is 17.8 or higher (required for .NET 8)
Test Docker integration:
  1. Open the AspNetRun solution
  2. Right-click the docker-compose project
  3. Verify “Docker” appears in the context menu

​
Optional Development Tools

​
Visual Studio Code

A lightweight, cross-platform alternative to Visual Studio.
1

Install VS Code

Download from https://code.visualstudio.com/Install these extensions:
  • C# Dev Kit - C# language support
  • Docker - Docker integration
  • REST Client - Test APIs directly in VS Code
  • GitLens - Enhanced Git capabilities
2

Install .NET Tools

Install helpful .NET CLI tools:
dotnet tool install -g dotnet-ef
dotnet tool install -g dotnet-outdated-tool

​
Database Management Tools

For inspecting and managing the databases: PostgreSQL:
  • pgAdmin - Full-featured database management
  • DBeaver - Universal database tool
SQL Server: Redis:

​
API Testing Tools

Postman: Download Postman
  • Import API collections
  • Test REST endpoints
  • View response data
Insomnia: Download Insomnia
  • Lightweight alternative to Postman
  • GraphQL support

​
Git

Version control for source code management. 
# Download from https://git-scm.com/download/win
# Or use winget
winget install -e --id Git.Git
Verify installation: 
git --version
Configure Git: 
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

​
System Requirements

​
Minimum Requirements

  • Operating System: Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+)
  • Processor: Dual-core CPU (2 GHz or faster)
  • Memory: 8 GB RAM (4 GB for Docker, 4 GB for OS and tools)
  • Disk Space: 30 GB available
  • Network: Broadband internet for downloading images
  • Operating System: Windows 11, macOS 13+, or Linux (Ubuntu 22.04+)
  • Processor: Quad-core CPU (2.5 GHz or faster)
  • Memory: 16 GB RAM (8 GB for Docker, 8 GB for OS and tools)
  • Disk Space: 50 GB SSD
  • Network: High-speed internet

​
Verification Checklist

Before proceeding to the quickstart guide, verify all prerequisites:
1

Check .NET SDK

dotnet --version
# Should show: 8.0.x
2

Check Docker

docker --version
# Should show: Docker version 24.x or higher

docker-compose --version
# Should show: Docker Compose version v2.x or higher
3

Verify Docker is Running

docker ps
# Should show running containers or empty list (no errors)
4

Check Available Resources

Open Docker Desktop and verify:
  • Memory allocation: 4 GB or more
  • CPU allocation: 2 cores or more
  • Available disk space: 20 GB or more
5

Test Docker Functionality

docker run --rm hello-world
# Should display welcome message
If all checks pass, you’re ready to proceed to the Quickstart Guide!

​
Troubleshooting

​
.NET SDK Not Found

If dotnet command is not recognized: Windows: Add .NET to PATH
  1. Search for “Environment Variables”
  2. Edit System Environment Variables
  3. Add C:\Program Files\dotnet to PATH
macOS/Linux: Add to shell profile 
echo 'export PATH=$PATH:/usr/local/share/dotnet' >> ~/.bashrc
source ~/.bashrc

​
Docker Desktop Won’t Start

Windows:
  • Enable Virtualization in BIOS
  • Install WSL 2: wsl --install
  • Update Windows to the latest version
macOS:
  • Enable Rosetta 2 for Apple Silicon: softwareupdate --install-rosetta
  • Grant Full Disk Access in System Preferences
Linux:
  • Check Docker service: sudo systemctl status docker
  • Start Docker: sudo systemctl start docker

​
Insufficient Permissions

Windows: Run Docker Desktop as Administrator Linux: Add user to docker group 
sudo usermod -aG docker $USER
newgrp docker

​
Port Conflicts

Check if required ports are available: 
# Windows
netstat -ano | findstr "5432 6379 1433 15672"

# Linux/macOS
lsof -i :5432 -i :6379 -i :1433 -i :15672
Required ports:
  • 5432, 5433: PostgreSQL
  • 6379: Redis
  • 1433: SQL Server
  • 5672, 15672: RabbitMQ
  • 6000-6005, 6060-6065: Microservices

​
Next Steps

With all prerequisites installed, you’re ready to run the application:

Quickstart Guide

Follow the step-by-step guide to run AspNetRun Microservices with Docker Compose

Build docs developers (and LLMs) love

Get started for freeTalk to us