Getting Started

Prerequisites

Tool	Version	Purpose
.NET SDK	10.0+	Backend API & migrations
Node.js	22+	Frontend dev server
Docker Desktop	Latest	MySQL container
Git	Any	Source control

1. Clone the Repository

git clone <repo-url>
cd MedRegiaApp

2. Configure Environment Variables

Copy the root .env template and fill in your local values:

cp .env.example .env

The file you need to edit:

# Local MySQL credentials (used by docker-compose.override.yml)
MYSQL_ROOT_PASSWORD=change_me_root
MYSQL_DATABASE=medregia_ca_db
MYSQL_USER=medregia
MYSQL_PASSWORD=change_me_app

# Host ports
API_PORT=5000        # maps to the API container's port 8080
FRONTEND_PORT=5173   # maps to the frontend Nginx container
DOCS_PORT=4040       # maps to the VitePress docs server

# Full connection string (must match the MySQL vars above)
DB_CONNECTION_STRING=Server=db;Port=3306;Database=medregia_ca_db;Uid=medregia;Pwd=change_me_app;SslMode=None;

See Environment Variables for the full reference.

Configure the Backend (for dotnet run)

If you plan to run the API directly with dotnet run (outside Docker), update backend/MedRegia.API/appsettings.Development.json so the API can reach the Dockerised MySQL:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Port=3306;Database=medregia_ca_db;Uid=medregia;Pwd=change_me_app;SslMode=None;AllowPublicKeyRetrieval=True;"
  },
  "Jwt": {
    "SecretKey": "dev_only_secret_key_32_chars_minimum"
  }
}

Match Uid/Pwd to MYSQL_USER/MYSQL_PASSWORD from your .env.

Configure the Frontend (for npm run dev)

Copy the frontend .env template:

cp frontend/.env.example frontend/.env

The default points to the locally running API:

VITE_API_BASE_URL=http://localhost:5000/api

3. Start the Database

Docker Compose automatically merges docker-compose.yml and docker-compose.override.yml, so a single command starts the local MySQL container:

docker compose up -d db

This starts MySQL 8.4 on localhost:3306 with the medregia_ca_db database. The container uses a health-check, so it will be ready before dependent services start.

4. Run Migrations

dotnet run --project backend/MedRegia.Migrations

The migration runner has an interactive CLI — when launched with no arguments it prompts you to choose between running pending migrations or generating a new script file. DbUp discovers all *.sql scripts under Scripts/ and applies any that haven't been recorded in the schemaversions table yet.

Run this again whenever new migration scripts are added to the repository.

5. Start the API

dotnet run --project backend/MedRegia.API

URL	Description
http://localhost:5000	API root
http://localhost:5000/scalar/v1	Interactive OpenAPI (Scalar) UI

6. Start the Frontend

cd frontend
npm install
npm run dev

The Vite dev server starts at http://localhost:5173.

7. First-Run Onboarding

On first launch the frontend detects that no pharmacy has been set up and redirects you to /onboarding. Follow the wizard to:

1. Set up your pharmacy (creates the OwnPharmacy vendor record)
2. Create the admin user account

After completing onboarding, log in with the credentials you created.

---

Alternative: Full Docker Stack

To run the entire stack — database, API, frontend, and docs — in Docker without any local .NET or Node.js tooling:

docker compose up --build

Service	Default URL
Frontend (SPA)	http://localhost:5173
API	http://localhost:5000
Docs	http://localhost:4040

Ports come from your .env. The frontend Nginx container also reverse-proxies /api/* to the API container.

Migrations in Docker

The docker compose up command does not run migrations automatically. Run dotnet run --project backend/MedRegia.Migrations on your host (with the db container running) or exec into the migration container manually.

---

Running Tests

# Backend unit tests
dotnet test backend/MedRegia.API.Tests

# Frontend type-check + build check
cd frontend && npm run build

Useful Commands

Task	Command
Start only the DB	docker compose up -d db
Stop all containers	docker compose down
Destroy DB volume (reset data)	docker compose down -v
View API logs (Docker)	docker compose logs -f api
Re-run pending migrations	dotnet run --project backend/MedRegia.Migrations
Generate a new migration script	dotnet run --project backend/MedRegia.Migrations new --name <Description>

TypeScript errors will fail the build — use this as a pre-deployment check.