Skip to content

Quick Start Guide

Get the Cargonerds application up and running in minutes.

Prerequisites

Before you begin, ensure you have the following installed:

  • .NET 9.0 SDK or later - Download
  • Node.js v18 or v20 - Download
  • Docker Desktop - Download
  • Redis (via Docker or local install)
  • SQL Server (via Docker or local install)
  • Git - Download

Clone the Repository

git clone https://github.com/Cargonerds/CargonerdsApp.git
cd CargonerdsApp

Configure the Application

1. Update Connection Strings

Check the connection strings in the following files:

  • src/Cargonerds.AuthServer/appsettings.json
  • src/Cargonerds.HttpApi.Host/appsettings.json
  • src/Cargonerds.DbMigrator/appsettings.json
  • src/Cargonerds.Web.Public/appsettings.json

Default connection string (for local SQL Server in Docker): 

{
  "ConnectionStrings": {
    "Default": "Server=localhost,1433;Database=Cargonerds;User Id=sa;Password=myStrong(!)Password;TrustServerCertificate=true"
  }
}

2. Generate Signing Certificate

For the AuthServer, you need an OpenIddict signing certificate:

cd src/Cargonerds.AuthServer
dotnet dev-certs https -v -ep openiddict.pfx -p d9efcd01-fbd8-42b1-a9d1-a5cf44afe714

Note: d9efcd01-fbd8-42b1-a9d1-a5cf44afe714 is the default password. Change it for production.

Set Up Infrastructure

Start infrastructure dependencies with Docker Compose:

cd etc/docker
docker-compose up -d

This starts: - SQL Server on port 1433 - Redis on port 6379 - RabbitMQ on port 5672

Option 2: Using .NET Aspire (Automated)

.NET Aspire will automatically start required infrastructure when you run the AppHost.

Install Client-Side Dependencies

abp install-libs

This command installs all required JavaScript/CSS libraries.

Run Database Migrations

Create the database and apply migrations:

cd src/Cargonerds.DbMigrator
dotnet run

You should see output indicating successful migration and data seeding.

Run the Application

Run the AppHost project to start all services:

cd src/Cargonerds.AppHost
dotnet run

The Aspire dashboard will open automatically. You can access:

  • Aspire Dashboard: http://localhost:15000 (or as shown in console)
  • AuthServer: http://localhost:5000
  • API: http://localhost:6000
  • Public Web: http://localhost:7000
  • Blazor App: http://localhost:8000

Option 2: Manual Start

Start each service individually in separate terminals:

# Terminal 1: AuthServer
cd src/Cargonerds.AuthServer
dotnet run

# Terminal 2: API Host
cd src/Cargonerds.HttpApi.Host
dotnet run

# Terminal 3: Public Web
cd src/Cargonerds.Web.Public
dotnet run

# Terminal 4: Blazor App
cd src/Cargonerds.Blazor
dotnet run

Access the Application

Default Credentials

Admin User: - Username: admin - Password: 1q2w3E*

Application URLs

  • Public Web: Navigate to the Public Web URL (default: https://localhost:7000)
  • Blazor App: Navigate to the Blazor URL (default: https://localhost:8000)
  • API Swagger: Navigate to {API_URL}/swagger (default: https://localhost:6000/swagger)

Verify Installation

1. Check API Health

Navigate to the API health endpoint: 

https://localhost:6000/health

You should see a JSON response indicating the health status.

2. Test Authentication

  1. Navigate to the Blazor app
  2. Click "Login"
  3. Enter admin credentials
  4. You should be redirected back to the application

3. Test API

Using Swagger UI at https://localhost:6000/swagger:

  1. Click "Authorize"
  2. Use admin credentials
  3. Try the /api/app/book endpoints

Common Issues

Port Already in Use

If ports are already in use, you can change them in launchSettings.json files in each project's Properties folder.

Certificate Errors

If you encounter HTTPS certificate errors:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Database Connection Errors

  1. Verify SQL Server is running: 

    docker ps

  2. Check connection string in appsettings.json

  3. Verify SQL Server accepts connections: 

    sqlcmd -S localhost,1433 -U sa -P "myStrong(!)Password"

Redis Connection Errors

Verify Redis is running: 

docker ps | grep redis
redis-cli ping  # Should return PONG

Next Steps

Now that you have the application running:

  1. Explore the UI: Navigate through the Blazor application
  2. Try the API: Use Swagger to test API endpoints
  3. Review the Code: Start with the Book service as a simple example
  4. Read Architecture: Understand the layered architecture
  5. Learn ABP Patterns: Review ABP patterns

Development Workflow

For day-to-day development:

  1. Start Infrastructure: docker-compose up -d (if not using Aspire)
  2. Run AppHost: dotnet run in AppHost directory
  3. Make Changes: Edit code in your IDE
  4. Hot Reload: Changes are automatically reloaded
  5. Run Tests: dotnet test in the test project
  6. Commit Changes: Use Git to commit your work

Troubleshooting

Application Won't Start

  1. Check prerequisites are installed
  2. Verify Docker is running
  3. Check port availability
  4. Review logs in the console

Can't Login

  1. Verify AuthServer is running
  2. Check AuthServer logs
  3. Ensure database migrations ran successfully
  4. Try default admin credentials

API Returns 401 Unauthorized

  1. Verify you're authenticated
  2. Check token in Authorization header
  3. Verify permission configuration
  4. Check AuthServer is accessible

Getting Help

What's Next?