Local Development

Prerequisites

Required tools

Tool	Purpose	Install location
WSL2 + Ubuntu	Linux environment on Windows	Windows (for Windows contributors)
Docker Desktop	Container runtime	Windows
VS Code + Remote WSL	Editor	Windows
Android Studio	Android emulator	Windows
Git	Version control	WSL Ubuntu
Node.js LTS	JS/TS tooling	WSL Ubuntu
pnpm (v10+)	Package manager	WSL Ubuntu
Python 3.12	Backend runtime	WSL Ubuntu

info

On Linux or macOS, Docker and the other tools can be installed natively. The WSL2 setup is specific to Windows contributors.

---

First-time setup (Windows / WSL2)

1. Install WSL2 and Ubuntu

# In PowerShell as Administrator
wsl --install -d Ubuntu
wsl --update

Restart if prompted. Create your Linux username and password when Ubuntu first starts.

2. Configure Docker Desktop

In Docker Desktop settings, enable:

• Use WSL 2 based engine
• WSL integration for your Ubuntu distribution

Verify inside Ubuntu:

docker version
docker compose version

3. Install Node.js LTS and pnpm

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc

# Install Node.js LTS
nvm install --lts
nvm use --lts
nvm alias default 'lts/*'

# Install pnpm
npm install --global corepack@latest
corepack enable
corepack prepare pnpm@latest-10 --activate

4. Install Python 3.12

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv
python3 --version   # should be 3.12.x

---

Clone the repository

Keep the repository inside the WSL Linux filesystem, not under C:\.

mkdir -p ~/dev && cd ~/dev
git clone <repo-url> deti-maker-lab
cd deti-maker-lab
code .   # open in VS Code via WSL

---

Environment files

Copy and configure the following environment files before running the stack:

# PostgreSQL
cp infra/db/.env.postgres.example infra/db/.env.postgres

# Snipe-IT
cp infra/snipeit/.env.snipeit.example infra/snipeit/.env.snipeit

# API
cp apps/api/.env.example apps/api/.env

Key variables to configure in apps/api/.env:

Variable	Example	Notes
DATABASE_URL	postgresql+psycopg://makerlab_app:password@postgres:5432/makerlab	Matches PostgreSQL credentials
SNIPEIT_BASE_URL	http://snipeit	Internal Docker service name
SNIPEIT_API_TOKEN	(generated by bootstrap)	Leave blank initially
FRONTEND_URL	https://deti-makerlab.ua.pt/new	Or http://localhost:3000 for local-only
SSO_CALLBACK_URL	https://deti-makerlab.ua.pt/auth/auth	Must match SSO registration
DML_AUTH_KEY	(from SSO provider)	University OAuth1 client key
DML_AUTH_SECRET	(from SSO provider)	University OAuth1 client secret
JWT_SECRET_KEY	(strong random string)	Change from default
LAB_TECHNICIANS	tech@ua.pt	Comma-separated technician emails

---

Install dependencies

JavaScript / TypeScript (web, mobile)

# From the repo root
pnpm install

Python (backend API)

cd apps/api
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
cd ../..

Python (migration tool)

cd apps/migration
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd ../..

---

Start local infrastructure

docker compose -f infra/docker/docker-compose.yml up -d

This starts: PostgreSQL, Snipe-IT (MariaDB + app), and Nginx.

Bootstrap Snipe-IT (first time only):

./infra/docker/bootstrap-snipeit.sh

This creates the Snipe-IT admin user, generates an API token, and writes it to apps/api/.env.

---

Run the apps

Open separate terminals for each service:

Terminal 1 — Web frontend (http://localhost:3000)

pnpm --filter web dev

Terminal 2 — FastAPI backend (http://localhost:8000, Swagger: http://localhost:8000/docs)

pnpm --filter api dev

Terminal 3 — Mobile app (press a for Android, scan QR for Expo Go)

pnpm --filter mobile dev

Or run API + mobile together:

pnpm dev

---

Full stack with Nginx (domain-based testing)

For testing the complete production-like stack with Nginx, domain names, and HTTPS:

1. Start all Docker containers:

   docker compose -f infra/docker/docker-compose.yml up -d

2. Add the domain to your hosts file:

   • Windows (PowerShell as Administrator):

     Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "`n127.0.0.1  deti-makerlab.ua.pt" -Force
     ipconfig /flushdns

   • Linux/macOS:

     echo "127.0.0.1  deti-makerlab.ua.pt" | sudo tee -a /etc/hosts

3. Access:

   • https://deti-makerlab.ua.pt/new — web app
   • https://deti-makerlab.ua.pt/new/api/docs — API Swagger
   • https://deti-makerlab.ua.pt/new/snipe-it — Snipe-IT

   Accept the self-signed certificate warning in the browser.

---

Common commands reference

# Install all dependencies
pnpm install

# Run web frontend
pnpm --filter web dev

# Run API backend
pnpm --filter api dev

# Run mobile app
pnpm --filter mobile dev

# Start Docker stack
docker compose -f infra/docker/docker-compose.yml up -d

# Stop Docker stack (preserve data)
docker compose -f infra/docker/docker-compose.yml stop

# Stop and remove containers (preserve volumes)
docker compose -f infra/docker/docker-compose.yml down

# Reset everything including data
docker compose -f infra/docker/docker-compose.yml down -v

# Load seed data
docker compose -f infra/docker/docker-compose.yml exec -T postgres \
  psql -U makerlab -d makerlab < infra/db/init/seed.sql

---

Troubleshooting

docker: command not found inside WSL

• Ensure Docker Desktop is running.
• Check WSL integration is enabled for Ubuntu in Docker Desktop settings.
• Restart Docker Desktop.

pnpm version issues

npm install --global corepack@latest
corepack enable
corepack prepare pnpm@latest-10 --activate

Backend dependencies missing or uvicorn not found

cd apps/api
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

The pnpm --filter api dev script uses venv/bin/uvicorn — the virtual environment must be created in apps/api/venv/.

Expo cannot find Android emulator

• Open Android Studio first.
• Start an emulator from the Device Manager.
• Run the mobile app again.

Ports already in use

• Web / mobile: port 3000
• API: port 8000
• PostgreSQL: port 5432
• Snipe-IT: port 8080
• Stop conflicting processes or change the port in the relevant configuration.

Site can't be reached (DNS_PROBE_FINISHED_NXDOMAIN)

You are trying to access the domain-based stack without the hosts file entry. Add 127.0.0.1 deti-makerlab.ua.pt to your hosts file.