Dev Environment Setup¶

[!abstract] What You'll Learn By the end of this tutorial, you'll have the backend and frontend running locally.

Prerequisites¶

Before starting, install:

• .NET 10 SDK
• Node.js 20+
• PostgreSQL 16+
• Git

Step 1: Clone the Repository¶

git clone https://github.com/Filipxxd/unicorn-trails.git
cd unicorn-trails

Step 2: Set Up PostgreSQL¶

Create a database for local development:

CREATE DATABASE unicorn_trails_dev;

Note your connection string:

Host=localhost;Port=5432;Database=unicorn_trails_dev;Username=postgres;Password=yourpassword

Step 3: Configure the Backend¶

Navigate to the backend folder:

cd UnicornTrails.API

Edit UnicornTrails.API/appsettings.Development.json with your local settings:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=unicorn_trails_dev;Username=postgres;Password=yourpassword"
  },
  "Security": {
    "Secret": "your-development-secret-key-must-be-at-least-64-characters-long-for-jwt"
  },
  "ObjectStorage": {
    "Provider": "R2",
    "Endpoint": "http://localhost:9000",
    "AccessKeyId": "minioadmin",
    "SecretAccessKey": "minioadmin",
    "BucketName": "unicorn-trails-dev"
  }
}

[!tip] Object Storage For local development, you can use MinIO as an S3-compatible storage. Or skip image features initially by leaving ObjectStorage unconfigured.

Step 4: Run Database Migrations¶

dotnet ef database update --project UnicornTrails.API.Infrastructure --startup-project UnicornTrails.API

Step 5: Start the Backend¶

dotnet run --project UnicornTrails.API

The API should be available at https://localhost:7001 (or the port shown in output).

Verify by visiting: https://localhost:7001/swagger

Step 6: Configure the Frontend¶

Open a new terminal and navigate to the frontend:

cd UnicornTrails.Client

Copy the example environment file:

cp .env.example .env

Edit .env:

VITE_API_URL=https://localhost:7001

Step 7: Install Frontend Dependencies¶

npm install

Step 8: Start the Frontend¶

npm run dev

The app should be available at http://localhost:5173.

Verify Everything Works¶

1. Open http://localhost:5173 in your browser
2. You should see the login page
3. API requests should reach the backend (check Network tab)

Running Tests¶

Backend Tests¶

cd UnicornTrails.API
dotnet test UnicornTrails.API.sln

Frontend Tests¶

cd UnicornTrails.Client
npm run test:unit
npm run lint
npm run type-check

What's Next?¶

• Project Structure — Understand the codebase layout
• Architecture — Learn how components connect
• Testing Guide — Write and run tests

Troubleshooting¶

"Connection refused" on API calls¶

Cause: Backend not running or wrong port.

Fix: Check backend is running and VITE_API_URL in .env matches the actual port.

Database migration fails¶

Cause: PostgreSQL not running or wrong connection string.

Fix: Verify PostgreSQL is running and connection string in appsettings.Development.json is correct.

"Certificate error" in browser¶

Cause: .NET dev certificates not trusted.

Fix:

dotnet dev-certs https --trust