Setup.md

Setup

This document covers local development environment setup and requirements.

Prerequisites

Required Software

Software	Version	Purpose
.NET SDK	9.0.300+	Runtime and build tools
PostgreSQL	16+	Database
Docker	Latest	Containerized development
Git	2.x+	Version control

Optional Tools

Software	Purpose
Visual Studio 2022	IDE (Windows)
VS Code	Cross-platform IDE
Rider	JetBrains IDE
pgAdmin	PostgreSQL GUI
Postman	API testing

Quick Start

1. Clone the Repository

git clone https://github.com/your-org/OpenCashFlow.git
cd OpenCashFlow

2. Verify .NET SDK Version

dotnet --version
# Should output 9.0.300 or higher

The project uses a global.json file to enforce SDK version:

{
  "sdk": {
    "version": "9.0.300",
    "rollForward": "latestFeature"
  }
}

3. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env with your local values:

# Database connection
DEFAULT_CONN_STRING=Host=localhost;Database=opencashflow_db;Username=opencashflow;Password=your_password

# JWT Settings (generate a strong key for local development)
JWTSETTINGS__SECRETKEY=your_local_dev_jwt_secret_key_at_least_64_characters_long

# CORS (local development URLs)
CORS__ALLOWEDORIGINS__0=https://localhost:7001
CORS__ALLOWEDORIGINS__1=https://localhost:7002

# Application URLs
APPURL=https://localhost:7001

4. Start the Database

Option A: Docker (Recommended)

docker compose -f docker-compose.dev.yml up -d

This starts:

• PostgreSQL 16 on port 5432
• pgAdmin on port 5050 (optional)

Option B: Local PostgreSQL

1. Install PostgreSQL 16
2. Create a database:

CREATE DATABASE opencashflow_db;
CREATE USER opencashflow WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE opencashflow_db TO opencashflow;

5. Run Migrations

# From the repository root
dotnet ef database update \
  --project src/OpenCashFlow.Shared/OpenCashFlow.Shared.csproj \
  --startup-project src/OpenCashFlow.API/OpenCashFlow.API.csproj \
  --context ApplicationDbContext

Or use the helper script:

./scripts/create-migration.sh InitialCreate --apply

6. Restore Dependencies

dotnet restore OpenCashFlow.sln

7. Build the Solution

dotnet build OpenCashFlow.sln

8. Run the Applications

Open multiple terminals:

Terminal 1 - API:

dotnet run --project src/OpenCashFlow.API/OpenCashFlow.API.csproj
# Runs on https://localhost:7002

Terminal 2 - Web App:

dotnet run --project src/OpenCashFlow.App/OpenCashFlow.App.csproj
# Runs on https://localhost:7001

Terminal 3 - Admin (optional):

dotnet run --project src/OpenCashFlow.Admin/OpenCashFlow.Admin.csproj
# Runs on https://localhost:7003

9. Access the Application

• Web App: https://localhost:7001
• API: https://localhost:7002
• Swagger UI: https://localhost:7002/swagger
• Admin Panel: https://localhost:7003

Docker Development

Full Stack with Docker Compose

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop all services
docker compose down

Docker Compose Services

The docker-compose.yml defines:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: opencashflow_db
      POSTGRES_USER: opencashflow
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  api:
    build:
      context: .
      dockerfile: src/OpenCashFlow.API/Dockerfile
    ports:
      - "7002:443"
    depends_on:
      - db

  app:
    build:
      context: .
      dockerfile: src/OpenCashFlow.App/Dockerfile
    ports:
      - "7001:443"
    depends_on:
      - api

IDE Setup

Visual Studio 2022

1. Open OpenCashFlow.sln
2. Set multiple startup projects:
   • Right-click Solution → Properties
   • Select "Multiple startup projects"
   • Set OpenCashFlow.API and OpenCashFlow.App to "Start"

VS Code

1. Install extensions:

   • C# Dev Kit
   • .NET Extension Pack
   • PostgreSQL (optional)

2. Use provided launch configurations in .vscode/launch.json

3. Run using the debug panel (F5)

Rider

1. Open the solution file
2. Configure compound run configuration for API + App

HTTPS Certificates

Development Certificates

ASP.NET Core uses development certificates. Trust them:

dotnet dev-certs https --trust

Certificate Issues

If you encounter certificate errors:

# Clean existing certificates
dotnet dev-certs https --clean

# Generate new trusted certificate
dotnet dev-certs https --trust

Hosts File (Optional)

For local domain simulation, add to /etc/hosts (macOS/Linux) or C:\Windows\System32\drivers\etc\hosts (Windows):

127.0.0.1 app.opencashflow.local
127.0.0.1 api.opencashflow.local
127.0.0.1 admin.opencashflow.local

Then update appsettings.Development.json accordingly.

Seed Data

The initial migration includes seed data:

Default Roles

Role	Purpose
Administrator	Full access to company resources
Employee	Standard user access
GIManagers	System-level admin (hidden)

Demo User

• Email: demo@opencashflow.local
• Password: DemoPassword123!
• Role: Administrator

Payment Methods

• Cash
• Bank Transfer
• Credit Card
• PayPal

Document Types

• Invoice
• Receipt
• Credit Note
• Other

Troubleshooting

Database Connection Failed

Npgsql.NpgsqlException: Failed to connect

Solution:

1. Verify PostgreSQL is running: docker ps or check service status
2. Check connection string in .env
3. Ensure the database exists
4. Check firewall/network settings

Migration Errors

Build failed

Solution:

1. Ensure the Shared project builds: dotnet build src/OpenCashFlow.Shared
2. Check for missing packages: dotnet restore
3. Verify .NET SDK version

Port Already in Use

System.IO.IOException: Failed to bind to address

Solution:

1. Find the process: lsof -i :7001 (macOS/Linux) or netstat -ano | findstr :7001 (Windows)
2. Kill the process or use different ports in launchSettings.json

CORS Errors

Access-Control-Allow-Origin header is missing

Solution:

1. Verify CORS__ALLOWEDORIGINS__* environment variables
2. Ensure the App URL matches the allowed origins exactly
3. Check that CORS middleware is configured before other middleware

Next Steps

1. Read Architecture to understand the system design
2. Review Configuration for environment setup
3. Check DevelopmentWorkflow for contribution guidelines