# Prerequisites

Required and optional software for Mosaic Stack development.

## Required

### Node.js 20+

```bash
# Install using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Verify installation
node --version  # Should be v20.x.x
```

### pnpm 9+

```bash
# Install globally
npm install -g pnpm@9

# Verify installation
pnpm --version  # Should be 9.x.x
```

### PostgreSQL 17+

**Option 1: Native Installation (Linux)**

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install postgresql-17 postgresql-contrib postgresql-17-pgvector

# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Verify installation
sudo -u postgres psql --version
```

**Option 2: macOS (Homebrew)**

```bash
brew install postgresql@17
brew services start postgresql@17
```

**Option 3: Docker (Recommended for Development)**

```bash
# PostgreSQL will be started via docker compose
# No native installation required
```

### Git 2+

```bash
# Ubuntu/Debian
sudo apt install git

# macOS
brew install git

# Verify installation
git --version
```

## Optional

### Docker & Docker Compose

Required for containerized deployment and recommended for development.

**Linux:**

```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker compose version
```

**macOS:**

```bash
# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop

# Verify installation
docker --version
docker compose version
```

### Authentik

Required for OIDC authentication in production.

**Docker Installation:**

```bash
# Download Authentik compose file
curl -o authentik-compose.yml https://goauthentik.io/docker-compose.yml

# Start Authentik
docker compose -f authentik-compose.yml up -d

# Access at http://localhost:9000
```

**Or use an existing Authentik instance**

See [Configuration → Authentik](../3-configuration/2-authentik.md) for setup instructions.

### Ollama

Required for AI features (optional for core functionality).

**Linux:**

```bash
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama2
```

**macOS:**

```bash
brew install ollama

# Pull a model
ollama pull llama2
```

**Or use remote Ollama instance**

Configure `OLLAMA_MODE=remote` and `OLLAMA_ENDPOINT` in `.env`.

## Verification

Check all required tools are installed:

```bash
node --version      # v20.x.x or higher
pnpm --version      # 9.x.x or higher
git --version       # 2.x.x or higher
docker --version    # 24.x.x or higher (if using Docker)
psql --version      # 17.x.x or higher (if using native PostgreSQL)
```

## Next Steps

Proceed to:
- [Local Setup](2-local-setup.md) for native development
- [Docker Setup](3-docker-setup.md) for containerized deployment