🚂 railhq.io - Model Railway Headquarters

railhq.io is a web-based control center for model railways. It provides a modern, browser-based interface to control locomotives, switches, signals, and more - all from any device on your network.

⚠️ Important Security Notice

Default credentials are set for quick start!

Username: free@railhq.io
Password: railhq.io

🔒 Please change these immediately after first login! See SECURITY.md for details.

✨ Features

• 🎮 Web-based Control - Control your model railway from any browser
• 🚂 Multi-Protocol Support - Works with ESU ECoS, Roco/Fleischmann z21, and HSI-88-USB
• 📱 Responsive Design - Works on desktop, tablet, and mobile devices
• 🔌 Local Gateway - Connect your command stations via the railhq Gateway
• 🎨 Visual Track Plan - Create and edit your track layout visually
• 🤖 Automation - Script-based automation for routes and sequences
• 👥 Multi-User - Multiple users can control the layout simultaneously

🏗️ Architecture

The system consists of three main components:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Web Browser   │───▶│   railhq.io     │───▶│    Gateway      │
│   (Any Device)  │◀───│   (Server)      │◀───│   (Local PC)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌───────────────┐
                                                │ Command       │
                                                │ Station       │
                                                │ (ECoS/z21)    │
                                                └───────────────┘

Components

Component	Description	Port
railyWebIndex	User management, login, workspace selection	80/443 (via nginx)
railyWebApp	Main application, track plan editor, control	5001
railyGateway	Local gateway connecting to command stations	8090
Redis	Session and cache storage	6379
nginx	Reverse proxy	80, 443

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Installation

# 1. Clone the repository
git clone https://github.com/cbries/railhq.io.git
cd railhq.io

# 2. Copy the example environment file
cp .env.example .env

# 3. Create data directories
mkdir -p ~/railhq.io/{resources,resourcesSetups,resourcesRedis,resourcesRuntime/nginx,resourcesRuntime/certificates,deployment}

# 4. Copy nginx configuration
cp resourcesRuntime/nginx/*.conf ~/railhq.io/resourcesRuntime/nginx/

# 5. Build and start
docker compose build railhq
docker compose up -d

Access

Open your browser and navigate to:

• http://localhost - Main application

Default credentials:

Username: free@railhq.io
Password: railhq.io

⚠️ CRITICAL SECURITY NOTICE: Change the default password immediately after first login! See SECURITY.md for important security information.

📖 Documentation

• INSTALL.md - Detailed installation guide
• CONTRIBUTING.md - How to contribute
• Gateway/railyHsi88Usb/README.md - HSI-88-USB documentation

🔧 Configuration

Environment Variables

Variable	Description	Default
RAILHQ_DATA_DIR	Base path for all data	~/railhq.io
RAILHQ_LOCAL_MODE	Enable local/LAN mode	true
RAILHQ_USE_TLS	Enable HTTPS	false
NGINX_CONF	nginx config file	nginx-http.conf

See .env.example for all available options.

Supported Command Stations

Manufacturer	Model	Status
ESU	ECoS	✅ Full support
Roco/Fleischmann	z21	✅ Full support
LDT	HSI-88-USB	✅ Feedback only

🛠️ Development

Local Development Setup

# Prerequisites
# - .NET 8.0 SDK
# - Node.js (for documentation)
# - Redis (local or Docker)

# Start Redis for development
docker compose -f docker-compose-redis.yml up -d

# Build and run (from VS Code or terminal)
dotnet build
dotnet run --project WebApp/railyWebIndex
dotnet run --project WebApp/railyWebApp

Project Structure

railhq.io/
├── Gateway/                 # Gateway application
│   ├── railyGateway/       # Main gateway
│   ├── railyEsuEcos/       # ESU ECoS driver
│   ├── railhqZ21/          # z21 driver
│   └── railyHsi88Usb/      # HSI-88-USB driver
├── WebApp/
│   ├── railyWebIndex/      # Login & user management
│   └── railyWebApp/        # Main web application
├── Libraries/              # Shared libraries
├── resources/              # Themes, demo data
└── docker-compose.yml      # Docker configuration

🐳 Docker

Build Image

# Build with documentation (recommended)
./docker-build_and_export.sh

# Build and save as tar.gz for deployment
./docker-build_and_export.sh --save

Run Services

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

Backup & Restore

# Create backup
docker compose run --rm backup

# Restore resources
docker compose run --rm restoreResources

🏗️ Building Gateway Locally

Build Gateway binaries for all platforms:

# Build all variants (Windows, Linux, macOS, Raspberry Pi)
./build-gateway-local.sh

# Build specific variant
./build-gateway-local.sh linux-x64

# List available variants
./build-gateway-local.sh --list

# Clean old builds
./build-gateway-local.sh --clean

Available Variants

Runtime	Platform	Description
win-x64	Windows	64-bit Intel/AMD
win-arm64	Windows	ARM64
linux-x64	Linux	64-bit Intel/AMD
linux-arm64	Linux	ARM64 (Raspberry Pi 4)
linux-arm	Linux	ARM (Raspberry Pi 3)
osx-x64	macOS	Intel
osx-arm64	macOS	Apple Silicon

🔄 CI/CD Pipelines

This project uses GitHub Actions for automated builds:

Workflow	Trigger	Output
docker-build.yml	Push to main, Tags v*	Docker Image → GHCR + Release
build-gateway.yml	Tags v*	Gateway Binaries (all platforms)

Docker Image

# Pull from GitHub Container Registry
docker pull ghcr.io/cbries/railhq.io:latest

# Or load from release tar.gz
gunzip -c railhq.io-1.64.tar.gz | docker load

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Dr. Christian Benjamin Ries

• Email: mail@cbries.de
• Website: www.riesolution.de
• Location: Bielefeld, Germany

🔒 Security

For security concerns, please review our Security Policy.

To report vulnerabilities, contact: mail@cbries.de

🙏 Acknowledgments

• ESU for the ECoS command station
• Roco/Fleischmann for the z21 command station
• LDT for the HSI-88-USB interface
• The model railway community

---

Made with ❤️ for the model railway community