GateKeeper

The Ultimate Self-Hosted Homelab Dashboard

GateKeeper is a Progressive Web App (PWA) that provides intelligent URL routing and proxy capabilities for self-hosted services. Perfect for remote access from workplace through a single tunnel.

Key Features

• Smart Network Detection - Auto-routes to internal/external URLs based on your location
• Manual Network Toggle - Override automatic detection with one-click switching
• Intelligent Proxy - Access services through GateKeeper when away from home
• SSH Terminals - Built-in web-based SSH client with multi-window support
• Bank-Level Security - AES-256-GCM encrypted credential storage
• Full PWA - Works offline, installable, real-time updates
• Single Port - Everything through one endpoint (perfect for tunneling!)
• Multi-User - Role-based access with admin management
• Real-Time Monitoring - Live service status indicators

Quick Deploy

One-Line Install

curl -fsSL https://raw.githubusercontent.com/resakse/gatekeeper/main/deploy.sh | bash

Docker Compose (Recommended)

git clone https://github.com/resakse/gatekeeper.git
cd gatekeeper
docker-compose up -d

Network Detection: GateKeeper automatically detects your network location using HTTP health checks on port 3004. You can manually override this detection using the network toggle in the floating menu.

Direct Docker

docker run -d \
  --name gatekeeper \
  -p 3002:3002 -p 3004:3004 \
  -e NODE_ENV=production \
  -e PORT=3002 \
  -e HOME_NETWORK_PORT=3004 \
  -v gatekeeper_data:/app/data \
  --restart unless-stopped \
  ghcr.io/resakse/gatekeeper:latest

Remote Access (Perfect for Workplace!)

Single Port = Easy Tunneling

Since GateKeeper runs on a single port (3002), you only need to expose ONE endpoint:

Option 1: Cloudflare Tunnel

# At home
cloudflared tunnel --url localhost:3002

# From workplace
https://random-name.trycloudflare.com

Option 2: Nginx Reverse Proxy (Production)

# Quick setup with included config
./setup-nginx.sh

# Or manual setup
docker-compose -f docker-compose.nginx.yml up -d

Full production-ready nginx config included with:

• SSL/TLS termination with Let's Encrypt support
• WebSocket upgrade for SSH terminals and real-time updates
• Security headers (HSTS, CSP, X-Frame-Options)
• Static asset caching for optimal PWA performance
• Rate limiting and DDoS protection
• Gzip compression for faster loading

Option 3: VPN Access

# Through Tailscale, WireGuard, etc.
https://home-server-ip:3002

Why Single Container?

Unlike complex multi-container setups, GateKeeper uses a single-container architecture:

• One port (3002) - Frontend + API + WebSockets
• One process - Bun serves everything
• One tunnel - Full remote access
• No CORS issues - Same origin
• No networking complexity - Everything local

Usage

1. Add Services - Configure your homelab services with internal/external URLs
2. Network Detection - GateKeeper auto-detects if you're home or away via HTTP health checks (port 3004)
3. Manual Override - Click the floating menu to manually toggle between Home/Public network modes
4. Smart Routing - Automatically routes to the best URL for your location
5. SSH Access - Open terminals directly to your servers
6. Proxy Mode - Access internal services through GateKeeper when remote

Offline Functionality

GateKeeper is a Progressive Web App (PWA) with comprehensive offline capabilities:

What Works Offline (No Internet/Tunnel)

Home Network Access:

• Browse all services - Direct access to internal URLs (192.168.x.x)
• SSH terminals - Full terminal access to local servers
• Service management - Add, edit, delete services (cached locally)
• Network detection - Detects home network even offline
• Settings configuration - All settings work without internet
• Real-time monitoring - Service status checks on local network
• PWA features - App works fully offline once cached
• Authentication - Login/logout with cached credentials
• Data persistence - All data stored locally in IndexedDB

Offline Queue:

• Automatic sync - Changes queue and sync when connection returns
• Background updates - Service worker handles offline operations
• Data integrity - No data loss during offline periods

What Requires Internet Connection

Remote Features:

• Proxy access - Cannot access internal services through GateKeeper proxy
• External service URLs - Public URLs (if different from internal)
• Icon fetching - Auto-fetching service icons from internet
• Software updates - PWA updates require internet connection
• Real-time imports - WebSocket-based service imports need connection

Limited Features:

• SSH to external hosts - Only works if SSH host is reachable locally
• Service icons - New services use default icons until online
• Network range detection - Auto-detection needs internet for initial setup

Smart Offline Behavior

Network-Aware Routing:

// GateKeeper automatically chooses best available option
if (offline && onHomeNetwork) {
  route = service.internalUrl    // Direct local access
} else if (online && external) {
  route = service.publicUrl || proxyUrl  // Remote access
} else if (offline && external) {
  route = "Service unavailable offline"  // Clear feedback
}

Offline Indicators:

• Red status - Service unreachable when offline
• Yellow status - Limited functionality (local only)
• Green status - Full functionality available

Offline Use Cases

Perfect for:

• Home network management - Full functionality without internet
• Server maintenance - SSH access during internet outages
• Travel setup - Configure services while offline, sync later
• Emergency access - Critical server access when internet is down
• Isolated networks - Air-gapped or restricted network environments

Example Offline Workflow:

# Internet goes down at home
1. GateKeeper detects home network (works offline)
2. All internal services remain accessible (192.168.x.x)
3. SSH terminals work to local servers
4. Can add/modify services (queued for sync)
5. When internet returns, changes sync automatically

This makes GateKeeper incredibly resilient - your homelab management never stops working, even during internet outages!

Network Scenarios Explained

Scenario	Location	Internet	Available Features
Home + Online	Home Network	Connected	Everything - Direct access + Proxy + SSH + Updates
Home + Offline	Home Network	No Internet	Local Full - Direct access + SSH + All management
Away + Tunnel	External + VPN/Tunnel	Connected	Remote Full - Proxy access + SSH + All features
Away + Public URLs	External	Connected	Direct External - Public URLs + Limited proxy
Away + Offline	External	No Internet	View Only - Cached services, no connectivity

Pro Tip: Configure both internalUrl AND publicUrl for maximum flexibility across all network scenarios!

Configuration

• Web Interface: http://localhost:3002
• Network Detection: HTTP health checks on port 3004
• Data Storage: /app/data (Docker volume)
• Environment: Set NODE_ENV=production for deployment
• Ports:
  • 3002 - Main application (configurable via PORT env var)
  • 3004 - Network detection health endpoint

Security Features

• AES-256-GCM Encryption - All SSH credentials encrypted client-side
• JWT Authentication - Secure multi-user access
• Master Password Protection - Auto-derived from network detection
• Role-Based Access - Admin and user roles
• HTTPS Ready - Deploy behind reverse proxy for TLS

System Requirements

• Docker - Any system running Docker
• Memory: 512MB RAM minimum
• Storage: 1GB for application + service data
• Network: Internet access for icon fetching and updates

Perfect For

• Homelab Enthusiasts - Manage all your self-hosted services
• Remote Workers - Access home services from workplace
• System Admins - SSH terminals + service monitoring in one place
• Privacy-Conscious Users - Self-hosted, no external dependencies

---

GateKeeper: One container, one port, infinite possibilities!