hop3-server 0.4.0b1

Simple PaaS - Deploy and manage web applications on a single server

hop3-server

Core server for the Hop3 Platform-as-a-Service.

Overview

hop3-server is the central orchestrator that handles application deployments, process management, reverse proxy configuration, and addon services. It provides a JSON-RPC API for communication with hop3-cli and hop3-tui.

Features

• Git-push deployments - Deploy applications via git push
• Automatic build system - Detects language (Python, Node, Ruby, Go, Rust, etc.) and builds automatically
• Process management - Manages app processes based on Procfile via uWSGI
• Reverse proxy - Nginx/Caddy/Traefik with automatic SSL certificates
• Addon services - PostgreSQL, MySQL, Redis management
• Plugin architecture - Extensible via pluggy-based plugins
• JSON-RPC API - For CLI and TUI communication

Installation

For development

# From workspace root
cd packages/hop3-server
uv pip install -e ".[dev]"

Production installation

Use hop3-installer:

curl -LsSf https://hop3.cloud/install-server.py | sudo python3 -

Quick Start

# Run the server
hop3-server serve

# Run with specific host/port
hop3-server serve --host 0.0.0.0 --port 8000

Architecture

hop3-server/
├── src/hop3/
│   ├── server/              # Litestar ASGI application
│   │   ├── asgi.py          # App factory
│   │   ├── controllers/     # API endpoints
│   │   └── security/        # Authentication
│   ├── commands/            # RPC command handlers
│   ├── deployers/           # Deployment orchestration
│   ├── orm/                 # SQLAlchemy models (App, EnvVar)
│   ├── plugins/             # Plugin system
│   │   ├── build/           # Builders, language toolchains
│   │   ├── deploy/          # Deployers (uWSGI, static)
│   │   ├── proxy/           # Nginx, Caddy, Traefik
│   │   ├── oses/            # OS implementations
│   │   ├── postgresql/      # PostgreSQL addon
│   │   ├── mysql/           # MySQL addon
│   │   └── redis/           # Redis addon
│   ├── core/                # Core abstractions
│   │   ├── protocols.py     # Plugin protocols
│   │   ├── hookspecs.py     # Hook specifications
│   │   └── plugins.py       # Plugin manager
│   ├── toolchains/          # Language toolchains
│   ├── run/                 # Runtime process management
│   └── project/             # Procfile parsing
└── tests/
    ├── a_unit/              # Unit tests
    ├── b_integration/       # Integration tests
    ├── c_system/            # System tests
    └── d_e2e/               # End-to-end tests

Deployment Flow

git push → Git hook → Deployer → Builder → Language Toolchain → uWSGI config → Nginx config

Filesystem Layout

/home/hop3/
├── apps/<app_name>/
│   ├── git/           # Bare git repository
│   ├── src/           # Checked-out source code
│   ├── data/          # Persistent data
│   ├── log/           # Log files
│   └── venv/          # Python virtualenv (if applicable)
├── nginx/             # Nginx configs and certs
├── uwsgi-available/   # uWSGI configs
├── uwsgi-enabled/     # Active uWSGI configs (symlinks)
└── hop3.db            # SQLite database

Configuration

Server configuration via environment variables or /etc/hop3/config.toml:

Variable	Description	Default
HOP3_HOME	Home directory	/home/hop3
HOP3_DATABASE_URL	Database URL	sqlite:///hop3.db
HOP3_SECRET_KEY	JWT signing key	(required)

Development

Running tests

# Unit tests
uv run pytest tests/a_unit/ -v

# Integration tests
uv run pytest -n 4 tests/b_integration/ -v

# System tests (requires Docker)
uv run pytest tests/c_system/ -v

# E2E tests (slow)
uv run pytest tests/d_e2e/ -v

Code quality

uv run ruff check src/
uv run ruff format src/
uv run pyright src/

Plugin Development

See Plugin Development Guide for creating:

• Language toolchains (new language support)
• Addons (new backing services)
• Deployers (new runtime strategies)
• Proxies (new reverse proxy support)

Documentation

• User Guide: Main documentation
• System Architecture: Architecture overview
• Plugin Development: Plugin guide
• Testing Strategy: Testing guide
• Package Internals: Deep-dive documentation

Related Packages

• hop3-cli - CLI client for this server
• hop3-tui - TUI client for this server
• hop3-installer - Installation tools

License

Apache-2.0 - Copyright (c) 2024-2025, Abilian SAS