🖥️ VyManager

Enterprise-grade VyOS Router Management System

🎯 Open Beta Community Release

➡️ Skip to Quick Start

📸 Screenshots

🚀 Quick Start

Prerequisites

🔧 Setup Guide

Step 1: Setup VyOS Router REST API

# Enter configuration mode
configure
# Create an API key (replace YOUR_SECURE_API_KEY with a strong random key)
set service https api keys id vymanager key YOUR_SECURE_API_KEY
# Enable REST functionality (VyOS 1.5+ only)
set service https api rest
# Optional: Enable GraphQL
set service https api graphql
# Save and apply
commit
save
exit

Step 2: Configure Environment Files

Frontend Configuration

cp frontend/.env.example frontend/.env

# Authentication (CHANGE THIS!)
BETTER_AUTH_SECRET=your-super-secret-key-change-in-production-CHANGE-THIS
# Leave these as default for Docker deployment
NODE_ENV=production
VYMANAGER_ENV=production
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://backend:8000
# Database (change password in production!)
DATABASE_URL=postgresql://vymanager:vymanager_secure_password@postgres:5432/vymanager_auth
# Add your server IP if accessing from other machines
TRUSTED_ORIGINS=http://localhost:3000,http://192.168.1.100:3000

Backend Configuration

cp backend/.env.example backend/.env

# Database Connection
DATABASE_URL=postgresql://vymanager:vymanager_secure_password@postgres:5432/vymanager_auth
# Frontend URL
FRONTEND_URL=http://localhost:3000

Step 3: Deploy with Docker Compose

# Enter pre-compiled images directory
cd /container/vymanager-prod
# Start all services
docker compose -f env-file-docker-compose.yml up -d
# View logs
docker compose logs -f
# Check status
docker compose ps

Step 4: Complete First-Time Setup Wizard

🏗️ Architecture Overview

Multi-Instance Management

Database-Driven Configuration

PostgreSQL Database
├── users # User accounts
├── sites # Site groupings
├── instances # VyOS router instances
├── permissions # User-site role mappings
└── active_sessions # Current connections

📁 Project Structure

vymanager/
├── frontend/ # Next.js 16 frontend application
│ ├── src/
│ │ ├── app/ # Next.js app router pages
│ │ │ ├── onboarding/ # First-time setup wizard
│ │ │ ├── sites/ # Site & instance management
│ │ │ ├── login/ # Authentication
│ │ │ └── [features]/ # VyOS configuration pages
│ │ ├── components/ # React components
│ │ │ ├── sites/ # Site management components
│ │ │ ├── layout/ # Navigation & layout
│ │ │ └── ui/ # shadcn/ui components
│ │ └── lib/ # Utilities and API clients
│ │ └── api/ # Backend API services
│ ├── prisma/ # Database schema & migrations
│ │ └── migrations/ # Multi-instance schema
│ ├── public/ # Static assets
│ └── Dockerfile # Frontend container
├── backend/ # FastAPI backend application
│ ├── routers/ # API route handlers
│ │ ├── session/ # Session & instance management
│ │ ├── firewall/ # Firewall configuration
│ │ ├── network/ # Network configuration
│ │ ├── interfaces/ # Interface management
│ │ └── [features]/ # Other VyOS features
│ ├── vyos_mappers/ # VyOS version mappers (1.4 vs 1.5)
│ ├── vyos_builders/ # Configuration builders
│ ├── vyos_service.py # VyOS device service layer
│ ├── app.py # Main FastAPI application
│ └── Dockerfile # Backend container
├── docker-compose.yml # Multi-service orchestration
│ ├── postgres # PostgreSQL database
│ ├── backend # FastAPI API server
│ └── frontend # Next.js web app
└── README.md # This file

🎨 Tech Stack

Frontend

Backend

Infrastructure

📜 Available Scripts

Docker Commands (Recommended)

# Start all services
docker compose up -d
# View logs
docker compose logs -f
docker compose logs -f backend # Backend only
docker compose logs -f frontend # Frontend only
# Stop all services
docker compose down
# Rebuild after code changes
docker compose build
docker compose up -d
# Restart a specific service
docker compose restart backend
docker compose restart frontend
# Clean everything (including database)
docker compose down -v

Root-level npm Commands

# Development
npm run dev # Start all services with Docker
npm run dev:down # Stop Docker services
# Production
npm start # Start services in detached mode
npm stop # Stop all services
# Logs
npm run logs # View all logs
npm run logs:frontend # Frontend logs only
npm run logs:backend # Backend logs only
# Build
npm run build:docker # Build Docker images
# Maintenance
npm run clean # Clean all build artifacts and containers

🔍 Managing Multiple VyOS Instances

Adding More Sites

Adding Instances to a Site

Connecting to an Instance

Switching Between Instances

🛡️ Role-Based Access Control

🏗️ Version-Aware Architecture

How It Works

Routers (API Endpoints)
 ↓
Builders (Batch Operations)
 ↓
Mappers (Version-Specific Commands)
 ↓
VyOS Device (1.4 or 1.5)

Capabilities Endpoint

{
 "version": "1.5",
 "features": {
 "domain_groups": {
 "supported": true,
 "description": "Domain-based firewall groups"
 },
 "ipv6_nat": {
 "supported": true,
 "description": "IPv6 NAT rules"
 }
 }
}

🧪 Development Setup

Frontend Development

cd frontend
# Install dependencies
npm install
# Run dev server (with hot reload)
npm run dev
# Type check
npm run type-check
# Lint
npm run lint
# Build for production
npm run build

Backend Development

cd backend
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run with auto-reload
uvicorn app:app --reload --host 0.0.0.0 --port 8000 --proxy-headers
> When serving behind Traefik/Nginx (HTTPS), make sure the proxy forwards `X-Forwarded-Proto`/`X-Forwarded-Port` so FastAPI can emit the correct scheme for redirects.
# View API docs
# Navigate to http://localhost:8000/docs

Database Migrations

cd frontend
# Generate migration after schema changes
npx prisma migrate dev --name migration_name
# Apply migrations
npx prisma migrate deploy
# View database
npx prisma studio

🐳 Docker Production Deployment

Using docker-compose.prod.yml

# Build images
docker compose -f docker-compose.prod.yml build
# Start services
docker compose -f docker-compose.prod.yml up -d
# View logs
docker compose -f docker-compose.prod.yml logs -f

Environment Variables for Production

NODE_ENV=production
BETTER_AUTH_SECRET=<strong-random-secret-256-bits>
BETTER_AUTH_SECURE_COOKIES=false
BETTER_AUTH_URL=https://vymanager.yourdomain.com
DATABASE_URL=postgresql://user:pass@postgres:5432/vymanager_auth
TRUSTED_ORIGINS=https://vymanager.yourdomain.com

DATABASE_URL=postgresql://user:pass@postgres:5432/vymanager_auth
FRONTEND_URL=https://vymanager.yourdomain.com

Reverse Proxy (Nginx)

server {
 listen 80;
 server_name vymanager.yourdomain.com;
 location / {
 proxy_pass http://localhost:3000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection 'upgrade';
 proxy_set_header Host $host;
 proxy_cache_bypass $http_upgrade;
 }
}

📚 Additional Documentation

🔒 Security Considerations

🤝 Contributing

🐛 Troubleshooting

Cannot Connect to VyOS Instance

Database Connection Failed

# Check if PostgreSQL is running
docker compose ps
# Check database logs
docker compose logs postgres
# Verify DATABASE_URL is correct in .env files

Frontend Build Errors

# Clear node_modules and rebuild
cd frontend
rm -rf node_modules .next
npm install
npm run build

Backend Import Errors

# Reinstall Python dependencies
cd backend
pip install -r requirements.txt --force-reinstall

📄 License

🆘 Support