Version 0.2.0

CLAUDE.md

@@ -0,0 +1,176 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Scotty is a Rust-based Micro-PaaS (Platform as a Service) that provides an API to manage Docker Compose-based applications. It consists of three main components:
+
+- **scotty**: HTTP server providing REST API and web UI for managing applications
+- **scottyctl**: CLI application for interacting with the Scotty server  
+- **scotty-core**: Core library containing shared data structures and settings
+
+## Architecture
+
+Scotty manages applications by:
+1. Scanning a configurable apps directory for folders containing `docker-compose.yml` files
+2. Reading optional `.scotty.yml` configuration files for app-specific settings
+3. Generating `docker-compose.override.yml` files with load balancer configurations (Traefik or HAProxy)
+4. Managing app lifecycle (create, start, stop, destroy) with TTL-based auto-cleanup
+5. Supporting app blueprints for common deployment patterns
+
+### Authentication Modes
+
+Scotty supports three authentication modes (configured via `auth_mode`):
+- **Development**: No authentication required, uses fixed dev user
+- **OAuth**: Authentication via oauth2-proxy with GitLab OIDC integration  
+- **Bearer**: Traditional token-based authentication
+
+Authentication is handled by the `basic_auth.rs` middleware which extracts user information based on the configured mode.
+
+## Development Commands
+
+### Building and Running
+
+```bash
+# Build all workspace members
+cargo build
+
+# Run the scotty server
+cargo run --bin scotty
+
+# Run the scottyctl CLI
+cargo run --bin scottyctl -- help
+
+# Run with specific configuration
+SCOTTY__API__AUTH_MODE=dev cargo run --bin scotty
+```
+
+### Frontend Development
+
+The frontend is a SvelteKit application with TypeScript:
+
+```bash
+cd frontend
+
+# Install dependencies (use bun instead of npm)
+bun install
+
+# Run development server  
+bun run dev
+
+# Build for production
+bun run build
+
+# Lint and format
+bun run lint
+bun run format
+```
+
+### Testing and Quality
+
+```bash
+# Run tests for all workspace members
+cargo test
+
+# Run tests for specific crate
+cargo test -p scotty-core
+
+# Check formatting
+cargo fmt --check
+
+# Run clippy linting
+cargo clippy --all-targets --all-features
+```
+
+### Release Management
+
+```bash
+# Update changelog using git-cliff
+git cliff > CHANGELOG.md
+
+# Create new release (example for alpha)
+cargo release --no-publish alpha -x --tag-prefix ""
+```
+
+## Configuration Structure
+
+### Main Configuration Files
+- `config/default.yaml`: Base configuration with all settings
+- `config/local.yaml`: Local overrides for development
+- `config/blueprints/`: App blueprint definitions (drupal-lagoon.yaml, nginx-lagoon.yaml)
+
+### OAuth Development Setup
+The `examples/oauth2-proxy/` directory contains a complete OAuth development environment:
+
+```bash
+cd examples/oauth2-proxy
+
+# Start in development mode (no auth)
+./start-dev.sh dev
+
+# Start with OAuth (requires GitLab app configuration)  
+op run --env-file="./.env.1password" -- ./start-dev.sh oauth --build
+
+# Start in bearer token mode
+./start-dev.sh bearer
+```
+
+### Key Configuration Options
+
+- `auth_mode`: "dev", "oauth", or "bearer"
+- `bind_address`: Server bind address (default: "0.0.0.0:21342")
+- `apps.root_folder`: Directory to scan for applications
+- `load_balancer_type`: "Traefik" or "HaproxyConfig"
+- `traefik.network`: Docker network for Traefik integration
+- `docker.registries`: Private Docker registry configurations
+
+## App Management
+
+### App Types
+- **Owned**: Fully managed by Scotty, can be destroyed
+- **Supported**: Can be managed but not destroyed
+- **Unsupported**: Read-only, shown in UI but not manageable
+
+### App Structure
+```
+apps/
+├── my-app/
+│   ├── docker-compose.yml          # Required
+│   ├── .scotty.yml                 # Optional app settings  
+│   ├── docker-compose.override.yml # Generated by Scotty
+│   └── ... (other app files)
+```
+
+### Blueprints
+Blueprints provide common deployment patterns and are referenced during app creation. They define lifecycle hooks that execute at specific events (create, run, destroy).
+
+## API and CLI Integration
+
+The API is self-documenting via OpenAPI/Swagger at `/rapidoc` endpoint. The CLI (`scottyctl`) communicates with the server via this REST API using bearer token authentication.
+
+Key environment variables for CLI:
+- `SCOTTY_SERVER`: Server URL
+- `SCOTTY_ACCESS_TOKEN`: Authentication token
+
+## Load Balancer Integration
+
+Scotty generates appropriate configurations for:
+
+### Traefik (Preferred)
+- Uses Docker labels for service discovery
+- Supports custom middlewares, basic auth, robots.txt prevention
+- Automatic SSL via Let's Encrypt integration
+
+### HAProxy-Config (Legacy)  
+- Uses environment variables for configuration
+- Limited feature set compared to Traefik
+
+## Development Notes
+
+- Use workspace-level Cargo.toml for shared dependencies
+- Frontend uses Bun instead of npm for package management  
+- Conventional commits are enforced via git-cliff
+- Pre-push hooks via cargo-husky perform quality checks
+- Container apps directory must have identical paths on host and container for bind mounts
+- Use conventional commit messages