Environment Setup¶

Complete guide to setting up a Sartiq development environment from scratch.

Prerequisites¶

System Requirements¶

Requirement	Minimum	Recommended
OS	Fedora 43+, Linux Mint 22.3+, Ubuntu 24.04+, macOS 14+, Windows 11 (WSL2)	Fedora 43+, Ubuntu 24.04+
RAM	16 GB	32 GB
Disk	50 GB free	100 GB free
CPU	4 cores	8 cores

We run many services locally (backend, frontend, PostgreSQL, Redis, compute workers) and handle large image files regularly. Higher memory and storage prevent slowdowns and OOM issues during development.

All components are deployed with Docker, and we use dev containers during development. This ensures consistent environments across Linux, macOS, and WSL2.

Required Software¶

Software	Version	Purpose
Docker	29.1+	Container runtime
Docker Compose	5.0+	Multi-container orchestration
Python	3.12+	Backend runtime
uv	0.9+	Python package manager
Bun	1.3+	JavaScript runtime and package manager
Node.js	24+	Frontend runtime
Git	2.5+	Version control
Claude	Latest	AI-assisted development
Discord	Latest	Team communication
Remmina	Latest	Remote server management (SSH, FTP, VNC)

Installation Commands¶

Linux (Fedora)

# Core tools
sudo dnf install git python3.12 nodejs

# Docker
sudo dnf install docker docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Bun
curl -fsSL https://bun.sh/install | bash

# Claude Code
npm install -g @anthropic-ai/claude-code

# Remmina (remote desktop/SSH client)
sudo dnf install remmina

Linux (Ubuntu/Debian)

# Core tools
sudo apt update
sudo apt install git python3.12 python3.12-venv nodejs

# Docker (follow official docs for latest)
sudo apt install docker.io docker-compose-v2
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Bun
curl -fsSL https://bun.sh/install | bash

# Claude Code
npm install -g @anthropic-ai/claude-code

# Remmina
sudo apt install remmina

macOS (Homebrew)

brew install python@3.12 node uv bun git
brew install --cask docker remmina

# Claude Code
npm install -g @anthropic-ai/claude-code

Verify installations

python3 --version        # 3.12+
node --version           # 24+
bun --version            # 1.3+
uv --version             # 0.9+
docker --version         # 29.1+
docker compose version   # 5.0+
claude --version         # latest

Recommended Tools¶

Tool	Purpose
IntelliJ IDEA	Full-featured IDE
VS Code	Lightweight IDE
Cursor	AI-native IDE
Antigravity	AI-native IDE
DBeaver	Database GUI
Postman	API testing
Remmina	Remote server management (SSH, FTP, VNC, RDP)
lazydocker	Docker TUI

Remmina (or similar tools like Royal TSX on macOS, MobaXterm on Windows) is useful for managing multiple servers via SSH, FTP, and other protocols from a single interface.

Quick Start¶

Get the full stack running in under 5 minutes.

# 1. Clone the repository
git clone git@github.com:shootify-io/sartiq.git
cd sartiq

# 2. Copy environment files
cp .env.example .env
cp frontend/.env.example frontend/.env.local

# 3. Start infrastructure (PostgreSQL, Redis)
docker compose up -d

# 4. Set up backend
cd backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload &

# 5. Set up frontend
cd ../frontend
bun install
bun run generate-api-client
bun run dev &

# 6. Verify
curl http://localhost:8000/health     # Backend health check
open http://localhost:3000            # Frontend app

Backend Setup¶

Python Environment¶

Create and activate the virtual environment using uv:

cd backend

# Install dependencies (creates .venv automatically)
uv sync

# Activate the environment (optional, uv run handles this)
source .venv/bin/activate

# Verify Python version
python --version  # Should be 3.11+

Environment Variables¶

Create backend/.env from the example:

cp .env.example .env

Required variables:

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql+asyncpg://user:pass@localhost:5432/sartiq`
`REDIS_URL`	Redis connection string	`redis://localhost:6379/0`
`SECRET_KEY`	JWT signing key (32+ chars)	`your-super-secret-key-here-min-32-chars`
`ENVIRONMENT`	Runtime environment	`development`

Optional variables for integrations:

Variable	Description
`ANTHROPIC_API_KEY`	Claude API access
`FAL_KEY`	Fal.ai image generation
`GOOGLE_API_KEY`	Gemini API access
`SMTP_HOST`	Email server host
`SMTP_PORT`	Email server port

Database Setup¶

Start PostgreSQL via Docker Compose:

# From repository root
docker compose up -d postgres

# Verify connection
docker compose exec postgres psql -U sartiq -d sartiq -c "SELECT 1"

Run database migrations:

cd backend

# Apply all migrations
uv run alembic upgrade head

# Verify tables exist
uv run python -c "from app.models import User; print('Models loaded')"

Starting the Dev Server¶

cd backend

# Development mode with auto-reload
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Or using the Makefile
make dev

Verifying the Backend¶

# Health check
curl http://localhost:8000/health
# Expected: {"status": "healthy"}

# OpenAPI documentation
open http://localhost:8000/docs

# ReDoc documentation
open http://localhost:8000/redoc

Frontend Setup¶

Node.js Environment¶

cd frontend

# Install dependencies
bun install

# Verify installation
bun pm ls  # Should show dependency tree without errors

Environment Variables¶

Create frontend/.env.local:

cp .env.example .env.local

Required variables:

Variable	Description	Example
`NEXT_PUBLIC_API_URL`	Backend API base URL	`http://localhost:8000`
`NEXT_PUBLIC_APP_URL`	Frontend app URL	`http://localhost:3000`

Generate API Client¶

Generate TypeScript client from OpenAPI spec:

# Ensure backend is running first
bun run generate-api-client

# This creates src/api/generated/ with typed clients

Re-run this command whenever the backend API changes.

Starting the Dev Server¶

cd frontend

# Development mode with hot reload
bun run dev

# Or specify port
bun run dev -- --port 3001

Verifying the Frontend¶

Open http://localhost:3000
You should see the login page
Check browser console for errors
Verify API connection in Network tab

Database Management¶

Creating Migrations¶

When you modify SQLAlchemy models:

cd backend

# Generate migration from model changes
uv run alembic revision --autogenerate -m "Add user preferences table"

# Review the generated file in alembic/versions/
# Edit if autogenerate missed something

Applying Migrations¶

# Apply all pending migrations
uv run alembic upgrade head

# Apply specific migration
uv run alembic upgrade <revision_id>

# Check current revision
uv run alembic current

Rolling Back¶

# Rollback one migration
uv run alembic downgrade -1

# Rollback to specific revision
uv run alembic downgrade <revision_id>

# Rollback all (dangerous!)
uv run alembic downgrade base

Resetting the Database¶

For a complete reset during development:

# Option 1: Drop and recreate via Docker
docker compose down -v postgres
docker compose up -d postgres
uv run alembic upgrade head

# Option 2: Reset via Alembic
uv run alembic downgrade base
uv run alembic upgrade head

Seeding Test Data¶

cd backend

# Run seed script
uv run python scripts/seed_dev_data.py

# This creates:
# - Test users (user@example.com / password123)
# - Sample projects
# - Demo content

Common Issues & Troubleshooting¶

Port Conflicts¶

Symptom: "Address already in use" error

# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or use different port
uv run uvicorn app.main:app --port 8001

Database Connection Errors¶

Symptom: "Connection refused" or "FATAL: password authentication failed"

# Check if PostgreSQL is running
docker compose ps

# Check PostgreSQL logs
docker compose logs postgres

# Verify connection string in .env
# Format: postgresql+asyncpg://USER:PASSWORD@HOST:PORT/DATABASE

# Test connection directly
docker compose exec postgres psql -U sartiq -d sartiq

Environment Variable Issues¶

Symptom: KeyError or missing config errors

# Verify .env file exists and is loaded
cat backend/.env

# Check if variable is set in shell
echo $DATABASE_URL

# Python-dotenv debugging
python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.getenv('DATABASE_URL'))"

Docker Memory Issues¶

Symptom: Containers crash or OOM errors

# Check Docker resource usage
docker stats

# Increase Docker Desktop memory limit:
# Docker Desktop → Settings → Resources → Memory → 8GB+

# Clean up unused resources
docker system prune -a

Node.js / Bun Issues¶

Symptom: Dependency conflicts or module not found

# Clear bun cache
bun pm cache rm

# Remove node_modules and reinstall
rm -rf node_modules bun.lock
bun install

# Check for peer dependency issues
bun pm ls 2>&1 | grep "UNMET"

Migration Conflicts¶

Symptom: "Can't locate revision" or "Multiple head revisions"

# Check migration history
uv run alembic history

# Show current heads
uv run alembic heads

# Merge multiple heads
uv run alembic merge heads -m "Merge migrations"

IDE Configuration¶

VS Code Settings¶

Add to .vscode/settings.json:

{
  "python.defaultInterpreterPath": "./backend/.venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.autoImportCompletions": true,

  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },

  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  "typescript.tsdk": "frontend/node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Recommended Extensions¶

Extension	Purpose
Python (ms-python)	Python language support
Ruff (charliermarsh)	Python linting/formatting
Pylance (ms-python)	Python type checking
ESLint (dbaeumer)	JavaScript/TypeScript linting
Prettier (esbenp)	Code formatting
Tailwind CSS IntelliSense (bradlc)	Tailwind autocomplete
GitLens (eamodio)	Git integration
Docker (ms-azuretools)	Docker support
Thunder Client	API testing

Debugging Configuration¶

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Backend: FastAPI",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": ["app.main:app", "--reload"],
      "cwd": "${workspaceFolder}/backend",
      "envFile": "${workspaceFolder}/backend/.env"
    },
    {
      "name": "Backend: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "cwd": "${workspaceFolder}/backend",
      "envFile": "${workspaceFolder}/backend/.env"
    },
    {
      "name": "Frontend: Next.js",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}/frontend",
      "runtimeExecutable": "bun",
      "runtimeArgs": ["run", "dev"]
    },
    {
      "name": "Backend: pytest",
      "type": "debugpy",
      "request": "launch",
      "module": "pytest",
      "args": ["-v", "-x"],
      "cwd": "${workspaceFolder}/backend"
    }
  ]
}

Linting and Formatting¶

Backend (Python):

cd backend

# Format code
uv run ruff format .

# Lint and auto-fix
uv run ruff check --fix .

# Type check
uv run mypy app

Frontend (TypeScript):

cd frontend

# Format code
bun run format

# Lint and auto-fix
bun run lint -- --fix

# Type check
bun run type-check

Command Reference¶

Backend Commands¶

Command	Description
`uv sync`	Install dependencies
`uv run uvicorn app.main:app --reload`	Start dev server
`uv run pytest`	Run tests
`uv run pytest -x -v`	Run tests (stop on first failure, verbose)
`uv run alembic upgrade head`	Apply migrations
`uv run alembic revision --autogenerate -m "msg"`	Create migration
`uv run ruff format .`	Format code
`uv run ruff check --fix .`	Lint code
`uv run mypy app`	Type check

Frontend Commands¶

Command	Description
`bun install`	Install dependencies
`bun run dev`	Start dev server
`bun run build`	Production build
`bun run test`	Run tests
`bun run test:watch`	Run tests in watch mode
`bun run lint`	Lint code
`bun run format`	Format code
`bun run type-check`	Type check
`bun run generate-api-client`	Generate API client

Docker Commands¶

Command	Description
`docker compose up -d`	Start all services
`docker compose down`	Stop all services
`docker compose down -v`	Stop and remove volumes
`docker compose logs -f`	Follow logs
`docker compose ps`	List running services
`docker compose exec postgres psql -U sartiq`	PostgreSQL shell
`docker compose exec redis redis-cli`	Redis CLI