gsadmin/aegis
1
0
Fork 0
mirror of https://github.com/axieyangb/aegis.git synced 2026-09-10 01:35:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify getting-started: end at step 3, move config to separate docs

Browse Source 
Getting started now covers only bootstrap (download → set password → start).
Configuration (clusters, TLS, filter chains) is deferred to the tutorial
and envoy-config.md so the onboarding path stays linear.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Yang Yang Xie
2026-05-20 17:21:59 -07:00
parent 440260a0f6
commit 8b52fac5fe
1 changed files with 8 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started.md
+8 -52
View File
@@ -8,8 +8,6 @@
## 1. Download the starter files
Create a new directory for Aegis and download the required configuration files:
```bash
mkdir aegis && cd aegis
@@ -34,59 +32,17 @@ docker compose up -d
- Aegis dashboard: `http://localhost:8765`
- Default login: `admin` / `changeme` (or the password you set in `ADMIN_PASSWORD`)
On first boot, Aegis automatically seeds the database with a working baseline configuration — an HTTP listener (port 10080) that redirects to HTTPS and handles ACME challenges, and an HTTPS listener (port 10443) ready for SNI-based TLS routing. No file import required.
On first boot, Aegis automatically seeds the database with a working baseline — an HTTP listener (port 10080) and an HTTPS listener (port 10443). No file import required.
## 4. Add your first service
**Configure a backend cluster:**
Go to **Gateway → Clusters** and add a cluster pointing to your upstream service (hostname/IP + port).
**Configure TLS:**
- For an **internet-facing domain**: go to **Certificates → Signing Providers**, add an ACME provider (Let's Encrypt), then issue a cert for your domain. See [TLS with ACME](#tls-with-acme-lets-encrypt) below.
- For an **internal or lab service**: use the built-in Local CA — no domain, no open ports required. See [Local CA](#local-ca-for-internal-use) below.
**Wire your domain to the listener:**
Go to **Gateway → Listeners → https_listener** and add a filter chain for your domain: set the SNI match, point it to your cluster, and attach the TLS certificate secret.
You should see **"xDS synced"** in green on the Gateway page, confirming Envoy has loaded the configuration.
---
## TLS with ACME (Let's Encrypt)
For domains that are publicly reachable:
1. Go to **Certificates → Signing Providers → Add Provider**
2. Choose **ACME**, select **Let's Encrypt**, set your email, and pick a challenge type:
- **HTTP-01** — easiest; requires port 80 open and domain pointing here
- **DNS-01** — works behind NAT; requires Cloudflare / Route 53 / GoDaddy API access
3. Go to **Certificates → Managed Certs → Issue Certificate**, choose your provider and domain
4. Aegis solves the challenge and pushes the cert to Envoy SDS automatically
5. Auto-renewal runs 30 days before expiry — no action needed
---
## Local CA for internal use
For internal services, home lab, or dev environments where you don't have a public domain:
1. Go to **Certificates → Signing Providers → Add Provider**, choose **Local CA**
2. Go to **Certificates → Managed Certs → Issue Certificate**, select the Local CA provider and enter any hostname (e.g. `homelab.local`)
3. The cert is issued instantly and pushed to Envoy — no domain validation, no open ports
4. Download the **Root CA certificate** from the Certificates page and install it in your browser or OS trust store so the cert is trusted
By default Aegis auto-generates a 10-year ECDSA Root CA on first use. If you already have your own CA (corporate PKI, internal CA), you can import it instead: go to **Certificates → Local CA → Import CA** and upload your CA certificate and private key in PEM format. Aegis will use your CA to sign all subsequent leaf certificates.
All certs issued by the Local CA auto-renew via Aegis before expiry.
You should see **"xDS synced"** in green on the Gateway page, confirming Envoy has connected and loaded the configuration.
---
## What's next
- **Try the Local CA tutorial** — [Tutorial: Local HTTPS with whoami](tutorial-whoami-local-https.md) walks through adding a service, issuing a cert, and accessing it over HTTPS from your browser — a good end-to-end test of your setup
- **IP Intelligence** — enable AI classification in Settings → AI to automatically profile and classify every IP that hits your gateway
- **Notifications** — connect Telegram, Slack, or a webhook in Settings → Integrations to get alerted on threats and anomalies
- **Owl AI** — click the owl icon to chat with your gateway in plain language
Your gateway is running. Pick the path that matches your goal:
- **Test locally with a sample service** — follow the [Local HTTPS with whoami tutorial](tutorial-whoami-local-https.md) to add a service, issue a cert, and verify HTTPS end-to-end on your machine
- **Expose a real service over the internet** — see [Envoy configuration](envoy-config.md) for how to add clusters, configure filter chains, and issue ACME certificates (Let's Encrypt)
- **Set up notifications** — connect Telegram, Slack, or a webhook in Settings → Integrations
- **Enable AI threat analysis** — configure an AI provider in Settings → AI to automatically classify and block malicious IPs