Fork: 0
yangyangxie / aegis-public
Transfer to URL with SHA Find file
Newer
Older
aegis-public / docs / getting-started.md
@Jerry Xie Jerry Xie on 19 May 2 KB docs: add Cloudflare Tunnel exposure architecture guide and sequence diagrams
Raw Blame History

Getting Started

Requirements

  • Docker and Docker Compose
  • A domain pointing to your server (for TLS / ACME)
  • Port 8765 accessible on your local network (dashboard)
  • Ports 80 and 443 open if you want Envoy to handle public traffic

1. Download the starter files

Create a new directory for Aegis and download the required configuration files:

mkdir aegis && cd aegis

# Download docker-compose config
curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml

# Download Envoy bootstrap configuration
mkdir envoy
curl -o envoy/envoy.yaml https://raw.githubusercontent.com/axieyangb/aegis/main/envoy/envoy.yaml

# Download baseline database configuration
mkdir configs
curl -o configs/starter.json https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json

2. Set your admin password

Edit docker-compose.yml and change ADMIN_PASSWORD=changeme to something secure.

3. Start the gateway

docker compose up -d
  • Aegis dashboard: http://localhost:8765
  • Default login: admin / (your password)

4. Connect Envoy to Aegis (Importing baseline)

  1. Open the Aegis dashboard in your browser.
  2. Go to Gateway page.
  3. Click the Import button at the top right.
  4. Upload the configs/starter.json file you downloaded in Step 1.

This will seed Aegis's database with a standard baseline configuration (a port 80 listener that redirects to HTTPS and handles ACME challenges). Aegis will immediately generate the correct Envoy configuration and push it to Envoy via xDS.

You should see "xDS synced" in green on the Gateway page, confirming Envoy has successfully connected and loaded the configuration!

5. Add your first service

Go to Gateway → Clusters to configure your backend services, and Gateway → Listeners to edit the https_listener filter chains to route your domain to your new cluster.

6. Expose your Gateway to the Internet

To accept public traffic from the internet, you need to expose Envoy's ports. Refer to the Deployment Architectures Guide to choose and configure your setup:

  • Direct Exposure (Port Forwarding): For static public IP setups.
  • VPS Relay Tunnel (PROXY Protocol): For CGNAT, home labs, or privacy-focused setups (highly recommended to preserve client IPs and prevent auto-blocking your own tunnel!).