Files

Jason Woltje dd5b3117a7 docs: Restructure documentation with Bookstack-compatible hierarchy

- 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>

2026-01-28 17:46:33 -06:00

3.1 KiB

Raw Blame History

Prerequisites

Required and optional software for Mosaic Stack development.

Required

Node.js 20+

# 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+

# Install globally
npm install -g pnpm@9

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

PostgreSQL 17+

Option 1: Native Installation (Linux)

# 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)

brew install postgresql@17
brew services start postgresql@17

Option 3: Docker (Recommended for Development)

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

Git 2+

# 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:

# 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:

# 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:

# 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 for setup instructions.

Ollama

Required for AI features (optional for core functionality).

Linux:

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

# Pull a model
ollama pull llama2

macOS:

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:

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 for native development
Docker Setup for containerized deployment

3.1 KiB Raw Blame History