Err0 Server - Deployment Repository

This repository contains Docker Compose orchestration for deploying Err0 Server in split architecture mode with separate API and frontend containers.

This is the deployment repository. It references the API and frontend repositories as sibling directories.

Repository Structure

/path/to/your/projects/
├── err0server-api-oss/          # Backend API repository
├── err0server-frontend-oss/     # Frontend apps repository
└── err0server-deployment/       # THIS repository (orchestration)
    ├── docker-compose.yml
    ├── .env.example
    └── README.md

Architecture

┌─────────────────┐
│   PostgreSQL    │
│   (port 54321)  │
└────────┬────────┘
         │
         │
┌────────▼────────┐       ┌──────────────────┐
│   API Server    │◄──────┤  Frontend (Nginx)│
│  (ports 8080,   │       │   (port 80)      │
│   8443)         │       │                  │
│                 │       │  - /             │
│  - Vert.x API   │       │  - /login        │
│  - MCP endpoints│       │  - /accmgt       │
│  - Headless mode│       │  - /dashboard    │
│  - CORS enabled │       │  - /kb           │
└─────────────────┘       └──────────────────┘

Quick Start

1. Prerequisites

Docker and Docker Compose
Git

2. Clone All Three Repositories

Important: All three repositories must be sibling directories (in the same parent folder).

# Create a directory for all err0 repositories
mkdir -p ~/code/err0
cd ~/code/err0

# Clone the three repositories
git clone https://github.com/err0io/err0server-api-oss.git
git clone https://github.com/err0io/err0server-frontend-oss.git
git clone https://github.com/err0io/err0server-deployment.git

# Your directory structure should now look like:
# ~/code/err0/
# ├── err0server-api-oss/
# ├── err0server-frontend-oss/
# └── err0server-deployment/

Local development paths (if you're using local repos):

cd /Users/rplb/code/err0
# You should have:
# - err0server-api-oss/
# - err0server-frontend-oss/
# - err0server-deployment/

3. Configure Environment

cp .env.example .env
# Edit .env with your configuration

4. Build and Start Services

docker-compose up -d

This will:

Start PostgreSQL database
Run database migrations (Flyway)
Start API server in headless mode
Build and start frontend Nginx container

5. Access Applications

Frontend (Customer Portal): http://localhost
Login: http://localhost/login/
Account Management: http://localhost/accmgt/
Dashboard: http://localhost/dashboard/
Knowledge Base: http://localhost/kb/
API: https://localhost:8443

Versioning

This repository uses Semantic Versioning with automated releases via Semantic Release.

Current Version

Check the latest release for current version.

Version History

See CHANGELOG.md for detailed version history and release notes.

Contributing

We welcome contributions! Please follow these guidelines:

Commit Message Format

This project follows Conventional Commits:

type(scope): subject

Types:

feat: New service or configuration option (minor version bump)
fix: Bug fix in orchestration (patch version bump)
docs: Documentation changes
chore: Maintenance tasks
perf: Performance improvements
ci: CI/CD changes

Examples:

git commit -m "feat(compose): add Redis cache service"
git commit -m "fix(env): correct default PostgreSQL port"
git commit -m "docs(readme): update deployment instructions"

Interactive commits:

npm run commit

For detailed guidelines, see CONTRIBUTING.md.

Breaking Changes

For incompatible changes, include BREAKING CHANGE: in commit footer:

feat(postgres): upgrade to PostgreSQL 16

BREAKING CHANGE: Requires full database backup and restore.
See MIGRATION.md for upgrade instructions.

This triggers a major version bump (1.x.x → 2.0.0).

Services

PostgreSQL (postgres)

Port: 54321 (mapped to 5432 internally)
Database: err0db
User: postgres
Volume: pgdata (persistent storage)

API Server (api)

HTTP Port: 8080
HTTPS Port: 8443
Mode: Headless (no embedded web apps)
CORS: Enabled for frontend origin
Health Check: curl https://localhost:8443/~/config

Frontend (web)

Port: 80
Server: Nginx
Apps: 5 React SPAs served as static files
Health Check: curl http://localhost/health

Configuration

Environment Variables

Edit .env to configure:

# Database
DB_NAME=err0db
DB_USER=postgres
DB_PASSWORD=your_secure_password
DB_PORT=54321

# API
API_HTTP_PORT=8080
API_HTTPS_PORT=8443

# Frontend
WEB_PORT=80
API_BASE_URL=https://localhost:8443
CORS_ALLOWED_ORIGIN=http://localhost

Production Configuration

For production deployment:

# .env
DB_PASSWORD=very_secure_password_here
API_BASE_URL=https://api.err0.io
CORS_ALLOWED_ORIGIN=https://app.err0.io
WEB_PORT=443  # Use HTTPS

Management Commands

Start Services

docker-compose up -d

Stop Services

docker-compose down

View Logs

# All services
docker-compose logs -f

# API only
docker-compose logs -f api

# Frontend only
docker-compose logs -f web

# PostgreSQL only
docker-compose logs -f postgres

Restart Service

docker-compose restart api
docker-compose restart web

Rebuild After Code Changes

# Rebuild API
docker-compose build api
docker-compose up -d api

# Rebuild Frontend
docker-compose build web
docker-compose up -d web

Database Operations

# Access PostgreSQL shell
docker-compose exec postgres psql -U postgres -d err0db

# Run Flyway migrations manually
docker-compose exec api ./gradlew flywayMigrate

# Backup database
docker-compose exec postgres pg_dump -U postgres err0db > backup.sql

# Restore database
docker-compose exec -T postgres psql -U postgres err0db < backup.sql

Development Workflow

Local Development (Without Docker)

For active development, you may want to run services locally:

API Server:

cd err0server-api-oss
./docker-start.sh  # Start PostgreSQL only
./gradlew build
./start-err0server.sh

Frontend:

cd err0server-frontend-oss
yarn install
cd web/customer
yarn start  # Starts on port 3000 with hot reload

Hybrid Mode

Run API in Docker, frontend locally for hot reload:

# Start only API and database
docker-compose up -d postgres api

# Run frontend locally
cd err0server-frontend-oss/web/customer
REACT_APP_API_BASE_URL=https://localhost:8443 yarn start

Troubleshooting

API Not Starting

Check logs:

docker-compose logs api

Common issues:

Database not ready: Wait for PostgreSQL health check
Port conflict: Change API_HTTPS_PORT in .env
Config error: Verify config.json syntax

Frontend Not Loading

Check Nginx logs:

docker-compose logs web

Common issues:

API CORS error: Verify CORS_ALLOWED_ORIGIN matches frontend URL
Build failed: Check Node.js version (requires 16+)
404 errors: Verify all apps built successfully

Database Connection Issues

# Test connection
docker-compose exec postgres pg_isready -U postgres

# Check connection from API
docker-compose exec api curl http://localhost:8080/~/config

CORS Errors

Ensure CORS configuration matches:

In .env:

CORS_ALLOWED_ORIGIN=http://localhost

In API config (or via environment variable):

{
  "roles": {
    "err0-api-server": [{
      "cors_allowed_origin": "http://localhost"
    }]
  }
}

Production Deployment

SSL/TLS Certificates

For production, use proper SSL certificates:

API Server: Place certificates in err0server-api-oss/ssl/
Frontend: Configure Nginx with SSL or use reverse proxy (Caddy, Traefik)

Reverse Proxy Setup

Recommended production setup with Caddy:

app.err0.io {
  reverse_proxy err0-frontend:80
}

api.err0.io {
  reverse_proxy err0-api:8443 {
    transport http {
      tls_insecure_skip_verify
    }
  }
}

Scaling

Scale frontend horizontally:

docker-compose up -d --scale web=3

Use a load balancer (Nginx, HAProxy) to distribute traffic.

Monitoring

Health Checks

API: https://localhost:8443/~/config
Frontend: http://localhost/health
Database: docker-compose exec postgres pg_isready

Metrics

Docker Compose includes health checks. Integrate with monitoring:

Prometheus: Scrape /metrics endpoint (if configured)
Grafana: Visualize metrics
Loki: Aggregate logs

Backup and Recovery

Automated Backups

Create a backup script:

#!/bin/bash
# backup.sh
docker-compose exec postgres pg_dump -U postgres err0db | gzip > "backup-$(date +%Y%m%d-%H%M%S).sql.gz"

Run daily via cron:

0 2 * * * /path/to/backup.sh

Disaster Recovery

Stop services: docker-compose down
Restore volume: docker volume rm err0_pgdata
Restore database: (see Database Operations above)
Start services: docker-compose up -d

Related Repositories

API Server: err0server-api-oss
Frontend: err0server-frontend-oss
Agent: err0agent

Support

Documentation: https://err0.io/docs
Issues: Report in individual repositories

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
.husky		.husky
.env.example		.env.example
.gitignore		.gitignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
MIGRATION_SUMMARY.md		MIGRATION_SUMMARY.md
README.md		README.md
commitlint.config.js		commitlint.config.js
docker-compose.yml		docker-compose.yml
package.json		package.json

Err0-io/err0server-deployment

Folders and files

Latest commit

History

Repository files navigation

Err0 Server - Deployment Repository

Repository Structure

Architecture

Quick Start

1. Prerequisites

2. Clone All Three Repositories

3. Configure Environment

4. Build and Start Services

5. Access Applications

Versioning

Current Version

Version History

Contributing

Commit Message Format

Breaking Changes

Services

PostgreSQL (postgres)

API Server (api)

Frontend (web)

Configuration

Environment Variables

Production Configuration

Management Commands

Start Services

Stop Services

View Logs

Restart Service

Rebuild After Code Changes

Database Operations

Development Workflow

Local Development (Without Docker)

Hybrid Mode

Troubleshooting

API Not Starting

Frontend Not Loading

Database Connection Issues

CORS Errors

Production Deployment

SSL/TLS Certificates

Reverse Proxy Setup

Scaling

Monitoring

Health Checks

Metrics

Backup and Recovery

Automated Backups

Disaster Recovery

Related Repositories

Support

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages