Archon

Docker Site Management Platform

A powerful Terminal UI client and distributed node system for managing Docker-based web hosting across multiple servers.

🌐 Project Page · 📖 Documentation · 🚀 Quick Start

Overview

Archon simplifies the complexity of managing Docker containers across multiple servers. Whether you're running a single server or orchestrating deployments across a fleet of nodes, Archon provides a unified interface for:

Deploying containerized applications with automatic reverse proxy configuration
Managing SSL certificates via Let's Encrypt or manual upload
Configuring DNS records through Cloudflare, Route53, or manual management
Monitoring container health and deployment status in real-time

Architecture

System Flow

Archon follows a client-node architecture where the TUI client communicates with remote node servers via REST API and WebSocket connections.

1. TUI Client Layer

Beautiful terminal interface built with Bubbletea
Manages sites, domains, and node configurations
Sends deployment commands to remote nodes
Receives real-time progress updates via WebSocket

2. Node Server Layer

Runs on each hosting server
Orchestrates Docker container lifecycle
Configures reverse proxies (Nginx/Apache/Traefik)
Manages SSL certificates automatically

3. Deployment Flow

User → TUI → Node API → Docker + Proxy + SSL

When you deploy a site:

TUI sends deployment request to the target node
Node pulls the Docker image
Container is created with proper networking
Reverse proxy is configured for the domain
SSL certificate is obtained (if enabled)
Status is reported back to TUI in real-time

Project Architecture

Communication Protocols:

REST API — Standard operations (deploy, stop, restart, delete)
WebSocket — Real-time deployment progress with step-by-step feedback

Supported Reverse Proxies:

Nginx
Apache
Traefik (with Docker provider)

SSL Modes:

Let's Encrypt (automatic)
Manual certificate upload
Traefik auto-managed

Features

Archon TUI Client

Feature	Description
🖥️ Modern Terminal UI	Beautiful, mouse-enabled interface built with Bubbletea and Lipgloss
🗂️ Tab Navigation	Click or use keyboard to navigate between Dashboard, Sites, Domains, and Nodes
🚀 Site Management	Create, deploy, and manage Docker-based websites
🌐 Domain Management	Configure domains with DNS provider integration (Cloudflare, Route53, Manual)
🖧 Node Management	Manage multiple remote servers from one interface
📄 Configuration Files	Attach custom config files to containers (nginx.conf, php.ini, etc.)
📊 Real-time Status	Monitor deployment status, container health, and node availability
🖱️ Mouse Support	Full mouse support with clickable tabs and form fields

Archon Node Server

Feature	Description
🐳 Docker Integration	Deploy and manage containers with automatic networking
🔄 Multiple Proxies	Choose from Nginx, Apache, or Traefik
🔒 SSL Management	Manual upload, Let's Encrypt auto-renewal, or Traefik-managed
🔌 REST API	Full API for remote management and automation
💓 Health Monitoring	Track Docker status, proxy health, and container metrics
⚙️ Config Injection	Mount custom configuration files into containers

Screenshots

Dashboard — System overview and quick actions	Sites — Manage deployed applications
Domains — DNS and domain configuration	Nodes — Remote server management

View More Screenshots

Settings — Application configuration

Help — Keyboard shortcuts and documentation

Quick Start

Option 1: Using Install Script (Recommended)

# Clone the repository
git clone https://github.com/BlueBeard63/Archon.git
cd Archon/archon

# Run the install script
./install.sh

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/BlueBeard63/Archon.git
cd Archon/archon

# Build and install
go build -o archon
sudo cp archon /usr/local/bin/

Launch Archon

archon

On first launch, Archon creates a default configuration at ~/.config/archon/config.toml.

📘 Setting up Node Servers? See the Node Server Setup section or the detailed Node README.

Installation

Prerequisites

Component	Requirement
Go	1.22+ (for building from source)
Terminal	Mouse support recommended (iTerm2, Windows Terminal, Alacritty)
Docker	Required on node servers

TUI Client Dependencies

The client uses the following Go packages (automatically installed via go build):

Package	Purpose
`github.com/charmbracelet/bubbletea`	TUI framework
`github.com/charmbracelet/lipgloss`	Terminal styling
`github.com/charmbracelet/bubbles`	UI components
`github.com/lrstanley/bubblezone`	Mouse zone support
`github.com/google/uuid`	UUID generation
`github.com/pelletier/go-toml/v2`	TOML configuration

Node Server Requirements

Nginx Mode

Nginx installed
Permission to write to nginx config directory
Permission to reload nginx

Apache Mode

Apache2 installed with mod_proxy and mod_ssl enabled
Permission to write to apache config directory
Permission to reload apache

Traefik Mode

Traefik running as a Docker container
Traefik configured with Docker provider
Docker socket mounted to Traefik

Let's Encrypt SSL

Certbot installed
Port 80 accessible from internet
Valid domain pointing to server

Configuration

TUI Client Configuration

Located at ~/.config/archon/config.toml:

version = "1.0.0"

[settings]
auto_save = true
health_check_interval_secs = 60
default_dns_ttl = 3600
theme = "default"

# Nodes are defined here
[[nodes]]
id = "550e8400-e29b-41d4-a716-446655440000"
name = "Production Server"
api_endpoint = "https://server1.example.com:8080"
api_key = "your-secure-api-key"
ip_address = "192.168.1.100"
status = "online"

# Sites configuration
[[sites]]
id = "650e8400-e29b-41d4-a716-446655440001"
name = "mywebsite"
domain_id = "750e8400-e29b-41d4-a716-446655440002"
node_id = "550e8400-e29b-41d4-a716-446655440000"
docker_image = "nginx:latest"
port = 8080
ssl_enabled = true

# Domains configuration
[[domains]]
id = "750e8400-e29b-41d4-a716-446655440002"
name = "example.com"
traefik_enabled = false

[domains.dns_provider]
type = "cloudflare"
api_token = "your-cloudflare-token"
zone_id = "your-zone-id"

Node Server Configuration

Example: Nginx with Let's Encrypt

Create /etc/archon/node-config.toml:

[server]
host = "0.0.0.0"
port = 8080
api_key = "generate-a-strong-random-key-here"
data_dir = "/var/lib/archon"

[proxy]
type = "nginx"
config_dir = "/etc/nginx/sites-enabled"
reload_command = "nginx -s reload"

[docker]
host = "unix:///var/run/docker.sock"
network = "archon-net"

[ssl]
mode = "letsencrypt"
cert_dir = "/etc/archon/ssl"
email = "admin@example.com"

[letsencrypt]
enabled = true
email = "admin@example.com"
staging_mode = false

Example: Traefik with Auto SSL

[server]
host = "0.0.0.0"
port = 8080
api_key = "generate-a-strong-random-key-here"
data_dir = "/var/lib/archon"

[proxy]
type = "traefik"
config_dir = ""
reload_command = ""

[docker]
host = "unix:///var/run/docker.sock"
network = "archon-net"

[ssl]
mode = "traefik-auto"
cert_dir = ""
email = "admin@example.com"

See the node/README.md for more configuration examples.

Usage Guide

Setting Up a New Node

Install Node Server on your remote server (see Installation section above)
Configure the node with appropriate proxy and SSL settings
Start the node server as a systemd service or manually
Add the node in Archon TUI:
- Launch Archon TUI
- Click on the Nodes tab or press 3
- Press n to create a new node
- Fill in:
  - Name: Friendly name for the server
  - API Endpoint: http://server-ip:8080 or https://server-ip:8080
  - API Key: The key from your node-config.toml
  - IP Address: Server's public IP address
- Press Enter to save

Creating a Domain

Click on the Domains tab or press 2
Press n to create a new domain
Enter the domain name (e.g., example.com)
Domain is created with Manual DNS by default
To configure DNS provider (Cloudflare/Route53):
- Edit ~/.config/archon/config.toml
- Update the domain's dns_provider section
- Restart Archon TUI

DNS Provider Configuration:

[[domains]]
id = "..."
name = "example.com"

# For Cloudflare
[domains.dns_provider]
type = "cloudflare"
api_token = "your-cloudflare-api-token"
zone_id = "your-cloudflare-zone-id"

# For Route53
[domains.dns_provider]
type = "route53"
access_key = "your-aws-access-key"
secret_key = "your-aws-secret-key"
hosted_zone_id = "your-hosted-zone-id"

# For Manual DNS
[domains.dns_provider]
type = "manual"

Creating and Deploying a Site

Click on the Sites tab or press 1
Press n to create a new site
Fill in the form:
- Name: Site identifier (e.g., myapp)
- Domain: Domain name (must exist in Domains)
- Node: Node name (must exist in Nodes)
- Docker Image: Docker image to deploy (e.g., nginx:latest, wordpress:latest)
- Port: Internal container port (e.g., 80, 8080)
Press Enter to create the site
The site will be deployed to the selected node automatically

Managing DNS Records

Navigate to Domains tab
Select a domain and view DNS records
Add/edit/delete records as needed
For Cloudflare/Route53: Changes sync automatically
For Manual DNS: Configure records at your DNS provider manually

SSL Certificate Management

SSL is handled automatically by the node server based on its configuration:

Mode	Behavior
Let's Encrypt	Certificates generated automatically on deployment
Traefik Auto	Traefik handles SSL via Docker labels
Manual	Upload your own certificates when deploying

Attaching Configuration Files

Mount custom configuration files into containers:

[[sites.config_files]]
name = "nginx.conf"
container_path = "/etc/nginx/nginx.conf"
content = """
server {
    listen 80;
    server_name example.com;
}
"""

Keyboard Shortcuts

Global

Key	Action
`Ctrl+C` / `q`	Quit application
`Esc`	Go back / Cancel
`?`	Show help screen

Navigation

Key	Action
`0` / `Tab`	Dashboard
`1` / `s`	Sites
`2` / `d`	Domains
`3` / `n`	Nodes

Lists

Key	Action
`n` / `c`	Create new item
`Enter`	View details
`d`	Delete selected item

Forms

Key	Action
`Tab` / `Shift+Tab`	Navigate fields
`Enter`	Submit form
`Esc`	Cancel

🖱️ Mouse Support: Click on tabs, form fields, and menu items. Works in iTerm2, Windows Terminal, Alacritty, and most modern terminals.

Systemd Service

Run the node server as a systemd service for production deployments:

# /etc/systemd/system/archon-node.service
[Unit]
Description=Archon Node Server
After=network.target docker.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/archon-node --config /etc/archon/node-config.toml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable archon-node
sudo systemctl start archon-node

DNS Provider Setup

Cloudflare

Log in to Cloudflare dashboard
Go to My Profile > API Tokens
Create token with Zone - DNS - Edit permissions
Copy the token and zone ID
Add to domain configuration in config.toml

Route53

Create IAM user with route53:ChangeResourceRecordSets permission
Generate access key and secret key
Note your hosted zone ID
Add to domain configuration in config.toml

Manual DNS

For providers not yet supported, use manual mode. Archon will track records locally but won't sync them—configure at your DNS provider manually.

API Documentation

The node server exposes a REST API for automation. See node/README.md for full API documentation.

Quick API Examples

# Deploy a site
curl -X POST http://node-server:8080/api/v1/sites/deploy \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-here",
    "name": "myapp",
    "domain": "example.com",
    "docker_image": "nginx:latest",
    "port": 80,
    "ssl_enabled": true
  }'

# Check health
curl http://node-server:8080/health

# Get site status
curl http://node-server:8080/api/v1/sites/{siteID}/status \
  -H "Authorization: Bearer your-api-key"

Troubleshooting

TUI Client Issues

Config file not found:

mkdir -p ~/.config/archon
archon  # Will create default config on first run

Mouse clicks not working:

Ensure your terminal supports mouse events
Try iTerm2, Windows Terminal, or Alacritty
Check terminal settings for mouse support

Node Connection Issues

Verify node server is running: systemctl status archon-node
Check firewall allows port 8080
Verify API endpoint URL is correct
Ensure API key matches between TUI config and node config

Docker Deployment Issues

Check Docker is running: systemctl status docker
Verify Docker socket is accessible: docker ps
Check container logs for errors

SSL Certificate Errors

# Check certbot logs (Let's Encrypt mode)
sudo tail -f /var/log/letsencrypt/letsencrypt.log

# Verify domain points to server
dig example.com

# Test with staging mode first in config:
# staging_mode = true

Reverse Proxy Errors

# Test nginx config
sudo nginx -t

# Test apache config
sudo apache2ctl configtest

# Reload proxy
sudo systemctl reload nginx  # or apache2

Security

Area	Recommendation
API Keys	Use strong keys: `openssl rand -base64 32`
SSL Certificates	Restrict permissions: `chmod 600 /etc/archon/ssl/*.key`
Docker Socket	Run node as dedicated user or use Docker socket proxy
Firewall	Restrict API port: `ufw allow from YOUR_IP to any port 8080`
HTTPS	Use HTTPS for node API or run over VPN

Contributing

Contributions are welcome! Areas for improvement:

Additional DNS providers (Namecheap, GoDaddy, etc.)
Container metrics dashboard
Log streaming in TUI
Site templates / presets
Backup and restore functionality
Multi-container sites (docker-compose support)
Health check automation
Notification system (email, Slack, etc.)

Building from Source

# Build TUI client
cd archon && go build -o archon

# Build node server  
cd node && go build -o archon-node

Project Structure

Archon/
├── archon/                 # TUI client
│   ├── internal/
│   │   ├── app/           # Bubbletea application
│   │   ├── models/        # Data models
│   │   ├── state/         # Application state
│   │   ├── config/        # Configuration loader
│   │   ├── api/           # Node API client
│   │   ├── dns/           # DNS provider integrations
│   │   └── ui/            # UI components and screens
│   └── main.go
├── node/                   # Node server
│   ├── internal/
│   │   ├── api/           # API handlers
│   │   ├── docker/        # Docker integration
│   │   ├── proxy/         # Reverse proxy configs
│   │   └── ssl/           # SSL management
│   └── main.go
└── imgs/                   # Screenshots and diagrams

License

MIT License - See LICENSE file for details.

Acknowledgments

Built with these excellent open source projects:

Library	Purpose
Bubbletea	TUI framework
Lipgloss	Terminal styling
Bubbles	TUI components
Bubblezone	Mouse zone support
Docker	Container runtime
Traefik / Nginx / Apache	Reverse proxies
Let's Encrypt	Free SSL certificates

🌐 Project Page · 📖 Node Documentation · ⬆ Back to Top

Made with ❤️ for the self-hosting community

Name		Name	Last commit message	Last commit date
Latest commit History 116 Commits
.planning		.planning
archon		archon
client		client
docs		docs
imgs		imgs
node		node
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation