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.
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.
- 🎮 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
The system consists of three main components:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Web Browser │───▶│ railhq.io │───▶│ Gateway │
│ (Any Device) │◀───│ (Server) │◀───│ (Local PC) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌───────────────┐
│ Command │
│ Station │
│ (ECoS/z21) │
└───────────────┘
| 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 |
- Docker and Docker Compose
- Git
# 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 -dOpen 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.
- INSTALL.md - Detailed installation guide
- CONTRIBUTING.md - How to contribute
- Gateway/railyHsi88Usb/README.md - HSI-88-USB documentation
| 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.
| Manufacturer | Model | Status |
|---|---|---|
| ESU | ECoS | ✅ Full support |
| Roco/Fleischmann | z21 | ✅ Full support |
| LDT | HSI-88-USB | ✅ Feedback only |
# 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/railyWebApprailhq.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
# Build with documentation (recommended)
./docker-build_and_export.sh
# Build and save as tar.gz for deployment
./docker-build_and_export.sh --save# Start all services
docker compose up -d
# View logs
docker compose logs -f
# Stop services
docker compose down# Create backup
docker compose run --rm backup
# Restore resources
docker compose run --rm restoreResourcesBuild 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| 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 |
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) |
# 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 loadWe welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
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
For security concerns, please review our Security Policy.
To report vulnerabilities, contact: mail@cbries.de
- 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