Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
126 lines (92 loc) · 3.71 KB

GETTING_STARTED.md

File metadata and controls

126 lines (92 loc) · 3.71 KB

Getting Started with Ampel

Ampel is a PR dashboard application that provides traffic light status indicators for your pull requests across GitHub, GitLab, and Bitbucket.

Quick Start

Prerequisites

  • Rust 1.92+ (for backend development)
  • Node.js 20+ with pnpm (for frontend development)
  • Docker and Docker Compose (for containerized deployment)
  • PostgreSQL 16+ (or use Docker)
  • Make (optional, for unified commands)

Option 1: Run with Docker (Recommended)

The fastest way to get Ampel running:

# Clone the repository
git clone https://github.com/pacphi/ampel.git
cd ampel

# Copy environment template
cp .env.example .env

# Start all services
make docker-up
# Or without Make:
cd docker && docker compose up -d

Access the application at http://localhost:3000

See RUN.md for detailed Docker instructions.

Option 2: Local Development

For active development:

# Clone and setup
git clone https://github.com/pacphi/ampel.git
cd ampel
cp .env.example .env

# Install dependencies
make install

# Start PostgreSQL (via Docker or locally)
docker run -d --name ampel-postgres \
  -e POSTGRES_USER=ampel \
  -e POSTGRES_PASSWORD=ampel \
  -e POSTGRES_DB=ampel \
  -p 5432:5432 \
  postgres:16-alpine

# Start all services (run in separate terminals)
make dev-api      # Backend API
make dev-worker   # Background worker
make dev-frontend # Frontend dev server

See DEVELOPMENT.md for complete development setup.

Using Make Commands

Ampel provides a unified Makefile interface for common operations:

make help         # Show all available commands
make install      # Install all dependencies
make build        # Build everything
make test         # Run all tests
make lint         # Run all linters
make format       # Format all code
make docker-up    # Start with Docker

See make help for the full list of available commands.

Configuration

Required Environment Variables

Variable Description
DATABASE_URL PostgreSQL connection string
JWT_SECRET Secret key for JWT tokens (min 32 chars)
ENCRYPTION_KEY Base64-encoded 32-byte key for PAT encryption

Personal Access Tokens (PATs)

Connect Git providers using Personal Access Tokens:

  • GitHub: Create a PAT at https://github.com/settings/tokens
  • GitLab: Create a PAT at https://gitlab.com/-/profile/personal_access_tokens
  • Bitbucket: Create an App Password at https://bitbucket.org/account/settings/app-passwords/

See PAT_SETUP.md for detailed instructions on creating and configuring PATs.

See .env.example for all configuration options.

Project Structure

ampel/
├── crates/                 # Rust backend
│   ├── ampel-api/          # REST API server (Axum)
│   ├── ampel-core/         # Business logic & domain models
│   ├── ampel-db/           # Database layer (SeaORM)
│   ├── ampel-providers/    # Git provider integrations
│   └── ampel-worker/       # Background job processor
├── frontend/               # React SPA
├── docker/                 # Docker configuration
├── docs/                   # Documentation
└── Makefile                # Unified build commands

Next Steps