Err0 Server Backend

Java/Vert.x REST API for the Err0 error code management platform

This repository contains the backend API for Err0. The frontend is in a separate repository.

Quick Start with Docker

# Start PostgreSQL database
docker compose up -d postgres

# Build the fat JAR
./gradlew shadowJar

# Start the API server
docker compose up -d api

The API will be available at:

• HTTP: http://localhost:8080
• HTTPS: https://localhost:8443 (with SSL configured)

Architecture

• Backend: Java 11, Vert.x 4.5.4, PostgreSQL 16
• Framework: CoreFabric (SaaS framework)
• Build: Gradle (Kotlin DSL)
• Database Migrations: Flyway
• Deployment: Docker Compose

Development Setup

Prerequisites

• JDK 11+
• Docker and Docker Compose
• Gradle 7+ (or use the wrapper)

1. Start Database

docker compose up -d postgres

This starts PostgreSQL on port 54321 with the schema pre-initialized.

2. Configure

For local development:

cp config.json.example config.json
# Edit config.json to update network interfaces (lo0/en0) for your system

For Docker deployment, configuration is handled via environment variables in docker-compose.yml.

3. Build

./gradlew build              # Full build with tests
./gradlew build -x test      # Skip tests
./gradlew shadowJar          # Create fat JAR for deployment

4. Run

./start-err0server.sh        # Local development
# or
docker compose up api        # Docker deployment

Environment Variables

See .env.example for all available environment variables. Key variables:

Variable	Description	Default
DB_HOST	Database host	postgres
DB_PORT	Database port	5432
DB_NAME	Database name	err0db
DB_USER	Database user	postgres
DB_PASSWORD	Database password	password
CORS_ALLOWED_ORIGIN	Frontend origin	http://localhost:3000
ERR0_COOKIE_PASSPHRASE	Cookie encryption	(required for production)
ERR0_CREDENTIAL_PASSPHRASE	Credential encryption	(required for production)

Optional Integrations

OAuth Authentication

Configure OAuth for GitHub, Google, or Microsoft login:

export GITHUB_OAUTH_CLIENT_ID="your_client_id"
export GITHUB_OAUTH_CLIENT_SECRET="your_client_secret"

Email (Mailgun)

export MAILGUN_API_KEY="your_api_key"
export MAILGUN_DOMAIN="mg.yourdomain.com"

AI Integration (OpenAI)

export OPENAI_API_KEY="sk-..."

API Authentication

Cookie-Based (Web UI)

Traditional session-based authentication for the web UI.

API Key (MCP Server)

For programmatic access and MCP (Model Context Protocol) integration:

curl -H "Authorization: Bearer err0_live_..." \
     http://localhost:8080/~/mcp/error-codes/search \
     -d '{"query":"ERR-","limit":100}'

Scopes: read:errors, write:errors, read:projects, write:projects, admin:*

MCP Endpoints

Optimized endpoints for AI/MCP server integration:

• POST /~/mcp/error-codes/search - Search error codes
• GET /~/mcp/error-codes/:uuid - Get error code details
• POST /~/mcp/error-codes/create - Create error code
• GET /~/mcp/projects - List projects
• GET /~/mcp/projects/:uuid/context - Get project context

Testing

./gradlew test                      # Run tests (without UAT data)
./gradlew test -PrunUatTests=true   # Run all tests including UAT

For comprehensive integration testing, use err0-open-source-bundle which populates test data via the agent.

Database

The database schema is pre-initialized via docker/postgres/init.sql at baseline version 100. Future migrations use Flyway starting from V101.

./gradlew flywayInfo      # Check migration status
./gradlew flywayMigrate   # Apply pending migrations

Project Structure

src/main/java/io/err0/server/
├── Err0.java                  # Entry point
├── Err0Bootstrap.java         # Database pool initialization
├── api/
│   ├── ApiBase.java           # Base class for endpoints
│   ├── ApiKeyAuthProvider.java # API key authentication
│   ├── RBAC.java              # Access control
│   ├── customer/              # Customer portal
│   ├── dashboard/             # Dashboard
│   ├── login/                 # Authentication
│   ├── agent/                 # Agent API
│   └── mcp/                   # MCP endpoints
├── entities/                  # DTOs
└── system/                    # Core components

Docker Commands

docker compose up -d postgres     # Start database
docker compose up -d              # Start all services
docker compose down               # Stop services
docker compose down -v            # Stop and remove volumes
docker compose build              # Rebuild images
docker compose logs -f api        # View API logs

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow Conventional Commits
4. Run tests: ./gradlew test
5. Submit a pull request

See CLAUDE.md for development guidelines.

Related Repositories

• err0-server-fe - Frontend web applications
• err0-open-source-bundle - Full test suite
• err0agent - Error code collection agent

License

See LICENSE for details.