dd5b3117a7
- Organized docs into numbered shelf/book/chapter/page structure - Created comprehensive README.md with project overview - Added Getting Started book (quick start, installation, configuration) - Added Development book (workflow, testing, type sharing) - Added Architecture book (design principles, PDA-friendly patterns) - Added API Reference book (conventions, authentication) - Moved TYPE-SHARING.md to proper location - Updated all cross-references in main README - Created docs/README.md as master index - Removed old QA automation reports - Removed deprecated SETUP.md (content split into new structure) Documentation structure follows Bookstack best practices: - Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api - Numbered chapters and pages for ordering - Clear hierarchy and navigation - Cross-referenced throughout Complete documentation available at: docs/README.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
173 lines
3.1 KiB
Markdown
173 lines
3.1 KiB
Markdown
# 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
|