Quick Start

Quick Start

This guide walks you through protecting your first server with Lumos Gate. The entire process takes about 5 minutes once you have a VPS ready.

Prerequisites

Before you begin, make sure you have the following:

• A DDoS-protected VPS running Debian 12+ or Ubuntu 24.04+ (see VPS Providers for recommendations and Supported OS for the full compatibility list)
• SSH access to the VPS (root or sudo)
• Your origin server's IP address and port (the server you want to protect)
• A domain name you can point to the shield VPS

Tip: If you do not have a VPS yet, check the VPS Providers guide for recommendations on choosing a DDoS-protected VPS.

Step 1: Create a Lumos Gate Account

Sign up at lumosgate.com. No credit card is required to get started. The free tier includes basic server management so you can evaluate the platform before committing. See Plans for a comparison of available tiers.

Step 2: Add a Server in the Dashboard

Navigate to Dashboard -> Servers -> Add Server.

1. Enter a name for your server (e.g., "US East Shield" or "EU Proxy 1")
2. Click Create Server
3. A connection token will be displayed

Warning: The connection token is shown only once. Copy it immediately and store it securely. The token is hashed (SHA-256) before storage, so it cannot be retrieved later. If you lose it, you will need to decommission the server and create a new one.

For more details on server management, naming conventions, and status monitoring, see the Server Management guide.

Step 3: Install the Agent

SSH into your DDoS-protected VPS and run the install command with your token:

curl -fsSL https://get.lumosgate.com/install | LUMOS_TOKEN=YOUR_TOKEN bash

Replace YOUR_TOKEN with the token you copied in Step 2.

The installer will:

1. Check system requirements (OS, architecture, root access)
2. Install HAProxy if it is not already present
3. Back up any existing HAProxy configuration
4. Download and install the Lumos Agent binary
5. Run kernel tuning for optimal performance (BBR, conntrack, etc.)
6. Register the agent as a systemd service and start it
7. Connect to the Lumos dashboard

Note: If HAProxy is already installed, the installer will detect it, show you the existing configuration stats (number of frontends, backends, config lines), and ask for confirmation before proceeding. Use LUMOS_FORCE=1 to skip the confirmation prompt. Existing sites can later be imported through the Detected Sites feature.

After installation completes, your server should appear as Online in the dashboard within a few seconds.

Having trouble? Check the agent logs with journalctl -u lumos-agent -f or see the Agent Installation guide for detailed troubleshooting steps.

Step 4: Add a Domain

Navigate to Dashboard -> Domains -> Add Domain and fill in:

Click Create Domain. The configuration is pushed to the agent in real-time via WebSocket.

Tip: You can use private IPs as origins if your shield VPS and origin communicate over a private network. WireGuard tunnel IPs (10.x.x.x), Docker IPs (172.x.x.x), and localhost (127.x.x.x) are all supported. Only non-routable addresses like 0.0.0.0 and 169.254.x.x are blocked.

For more details on domain configuration, origin editing, and multi-server assignment, see the Domains guide.

Step 5: Point Your DNS

Update your domain's DNS records to point to your shield VPS IP address:

Type    Name              Value              TTL
A       example.com       <SHIELD_VPS_IP>    300
A       www.example.com   <SHIELD_VPS_IP>    300

Replace <SHIELD_VPS_IP> with the public IP address of your shield VPS.

Important: Use a short TTL (300 seconds) initially so you can quickly revert if anything goes wrong. You can increase it to 3600 or higher once everything is confirmed working.

Warning: Do not use Cloudflare's orange-cloud proxy (Proxied mode) when pointing DNS to your shield VPS. Use DNS-only (grey cloud) mode. Cloudflare's proxy would interfere with Lumos Gate's SSL provisioning and WAF. Your shield VPS already provides DDoS protection.

For complete DNS configuration instructions, including subdomain setup and provider-specific guides, see DNS Setup.

Step 6: Verify

Once DNS propagates (usually 1-5 minutes with a 300s TTL), visit your domain. You should see your origin site loading through the shield VPS.

To verify the proxy is working, check the response headers:

curl -I https://example.com

You should see a successful response. If you enabled SSL, the certificate will be provisioned automatically on the first request. This may take a few seconds on the very first visit while the ACME HTTP-01 challenge completes.

To confirm your origin IP is hidden, use an external DNS lookup tool and verify that only the shield VPS IP appears:

# Should show your shield VPS IP, NOT your origin IP
dig +short example.com

What Happens Behind the Scenes

Here is what happens after you complete the setup:

1. The dashboard pushes your domain configuration to the WebSocket server
2. The WebSocket server forwards it to the agent on your shield VPS
3. The agent generates the HAProxy configuration for your domain
4. If SSL is enabled, the agent provisions a Let's Encrypt certificate via ACME HTTP-01
5. HAProxy reloads with the new configuration (zero-downtime reload)
6. Incoming traffic to your domain now flows through the shield VPS to your origin

All of this happens within seconds of clicking "Create Domain." If anything goes wrong during the HAProxy reload, the agent automatically rolls back to the previous working configuration.

Recommended Post-Setup Steps

After your first domain is live, consider these additional hardening steps:

1. Lock down your origin -- Configure your origin firewall to only accept traffic from your shield VPS IP. This is the single most important step after initial setup.
2. Enable WAF -- Turn on WAF rules for your domain to protect against SQL injection, XSS, and other application-layer attacks.
3. Enable bot protection -- Set up bot protection to block automated scanners and bad bots.
4. Set up rate limiting -- Configure rate limiting to prevent abuse and HTTP flood attacks.

Next Steps

• Enable WAF rules to protect against application-layer attacks
• Set up bot protection to block automated abuse
• Configure IP blacklisting to block known malicious IPs
• Add rate limiting to prevent HTTP flood attacks
• Add multiple servers for redundancy and load distribution
• Configure DNS failover for automatic recovery when a shield goes down
• Set up notifications to get alerts when servers go down, SSL certificates expire, or balances run low
• Lock down your origin firewall to only accept traffic from shield VPS IPs
• Connect via WireGuard for encrypted origin communication over a private tunnel