mirror of
https://github.com/axieyangb/aegis.git
synced 2026-09-11 14:00:23 +00:00
fix: correct Envoy bootstrap architecture, docker-compose configuration, and installation docs
This commit is contained in:
Jerry Xie
@@ -20,25 +20,40 @@ Aegis sits between the internet and your services. It controls Envoy Proxy via x
|
||||
|
||||
## Quick start
|
||||
|
||||
### 1. Download the starter files
|
||||
|
||||
Create a directory and download the required files:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name aegis \
|
||||
-p 8765:8765 \
|
||||
-v aegis_data:/data \
|
||||
-e ADMIN_PASSWORD=changeme \
|
||||
axieyangb/aegis:latest
|
||||
mkdir aegis && cd aegis
|
||||
|
||||
# Download docker-compose config
|
||||
curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml
|
||||
|
||||
# Download Envoy static bootstrap config
|
||||
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
|
||||
```
|
||||
|
||||
Open `http://localhost:8765` — default login: `admin` / `changeme`
|
||||
|
||||
### With Envoy (recommended)
|
||||
### 2. Start the gateway
|
||||
|
||||
```bash
|
||||
curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml
|
||||
curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
* Open **`http://localhost:8765`** — default login: `admin` / `changeme` (Change the `ADMIN_PASSWORD` in `docker-compose.yml`!).
|
||||
|
||||
### 3. Import the baseline configuration
|
||||
|
||||
* Go to the **Gateway** page in the dashboard.
|
||||
* Click the **Import** button at the top right.
|
||||
* Upload the `configs/starter.json` file you downloaded.
|
||||
* You should see the `http_listener` and `https_listener` appear, and the xDS sync status turn green!
|
||||
|
||||
---
|
||||
|
||||
## Features in Action
|
||||
@@ -152,10 +167,8 @@ Mount a volume or directory to `/data`:
|
||||
|
||||
## Docs
|
||||
|
||||
- [Getting started](docs/getting-started.md)
|
||||
- [Envoy configuration](docs/envoy-config.md)
|
||||
- [AI setup (Owl chat + threat analysis)](docs/ai-setup.md)
|
||||
- [Notifications (Telegram, Discord, webhooks)](docs/notifications.md)
|
||||
* [Getting started](docs/getting-started.md)
|
||||
* [Envoy configuration](docs/envoy-config.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -191,5 +204,5 @@ Outside of work: smart home automation, DIY racing drones, home lab tinkering, 3
|
||||
|
||||
## Support & Enterprise
|
||||
|
||||
- **Issues & feature requests**: [GitHub Issues](https://github.com/axieyangb/aegis/issues)
|
||||
- **Enterprise collaboration, custom integrations, or just want to know more**: [yyangxie@gmail.com](mailto:yyangxie@gmail.com)
|
||||
* **Issues & feature requests**: [GitHub Issues](https://github.com/axieyangb/aegis/issues)
|
||||
* **Enterprise collaboration, custom integrations, or just want to know more**: [yyangxie@gmail.com](mailto:yyangxie@gmail.com)
|
||||
|
||||
+2
-2
@@ -24,11 +24,11 @@ services:
|
||||
- "80:10080"
|
||||
- "443:10443"
|
||||
volumes:
|
||||
- ./configs/starter.json:/etc/envoy/envoy.json:ro
|
||||
- ./envoy/envoy.yaml:/etc/envoy/envoy.yaml:ro
|
||||
command:
|
||||
- /usr/local/bin/envoy
|
||||
- -c
|
||||
- /etc/envoy/envoy.json
|
||||
- /etc/envoy/envoy.yaml
|
||||
- --log-level
|
||||
- warn
|
||||
networks:
|
||||
|
||||
+18
-54
@@ -1,67 +1,31 @@
|
||||
# Envoy Configuration
|
||||
|
||||
Aegis controls Envoy via xDS (ADS protocol). You configure everything through the Aegis UI — no manual YAML editing required.
|
||||
Aegis controls Envoy via xDS (specifically using the ADS - Aggregated Discovery Service - protocol). You configure everything through the Aegis UI — no manual YAML editing required.
|
||||
|
||||
## How it works
|
||||
|
||||
1. Envoy connects to Aegis at `aegis:18000` (gRPC ADS)
|
||||
2. Aegis pushes listeners, clusters, and secrets dynamically
|
||||
3. Changes in the Aegis UI take effect in Envoy within ~1 second
|
||||
1. Envoy starts using a static bootstrap file (`envoy.yaml`) pointing it to Aegis.
|
||||
2. Envoy connects to Aegis at `aegis:18000` (gRPC ADS).
|
||||
3. Aegis pushes listeners, clusters, and secrets dynamically from its database.
|
||||
4. Changes made in the Aegis UI take effect in Envoy within ~1 second.
|
||||
|
||||
## Static bootstrap (envoy.yaml / starter.json)
|
||||
## Static bootstrap (`envoy.yaml`)
|
||||
|
||||
Envoy needs a static bootstrap file to know where to find the xDS server. The provided `configs/starter.json` configures:
|
||||
Envoy needs a static bootstrap file to know where to find the xDS server. The provided `envoy/envoy.yaml` configures:
|
||||
|
||||
- xDS server: `aegis:18000`
|
||||
- Access log: streamed to Aegis via gRPC ALS (provides real-time traffic data)
|
||||
- Node ID: `home` (must match `NODE_ID` env var in Aegis)
|
||||
* **xDS server:** `aegis:18000` (using gRPC).
|
||||
* **Node ID:** `home` (must match `NODE_ID` env var in Aegis).
|
||||
* **Admin interface:** bound to port `9901` (internal or public as mapped in docker-compose).
|
||||
|
||||
**Do not add listeners or clusters to the bootstrap file** — manage them entirely through the Aegis Gateway UI.
|
||||
**Do not add listeners or clusters to this bootstrap file.** They should be managed entirely through the Aegis Gateway UI (and are stored in Aegis's database).
|
||||
|
||||
## Gateway concepts
|
||||
## Dynamic configuration (`starter.json`)
|
||||
|
||||
### Listeners
|
||||
A listener binds to a port and accepts connections. Typically:
|
||||
- One listener on port 80 (HTTP)
|
||||
- One listener on port 443 (HTTPS)
|
||||
The `configs/starter.json` is **not** read by Envoy. It is an export of the Aegis database structure. When imported via the Aegis UI, it configures:
|
||||
|
||||
### Filter chains
|
||||
Each listener can have multiple filter chains. A filter chain matches incoming connections (by SNI/domain) and routes them to a backend cluster. Each filter chain can have:
|
||||
- A TLS secret (for HTTPS)
|
||||
- A backend cluster
|
||||
- HTTP extensions (OIDC, rate limiting, Lua, etc.)
|
||||
* `http_listener` (port 10080): Redirects all standard HTTP traffic to HTTPS, but routes `/.well-known/acme-challenge` to the `acme-renewer` cluster.
|
||||
* `https_listener` (port 10443): Placeholder for your SSL traffic with SNI matching.
|
||||
* `acme-renewer` cluster: Points to Aegis's built-in ACME challenge responder.
|
||||
* `my-service` cluster: Placeholder for your actual backend application.
|
||||
|
||||
### Clusters
|
||||
An upstream cluster defines where traffic goes. Types:
|
||||
- `STATIC` — fixed IP/hostname (resolved once at startup)
|
||||
- `LOGICAL_DNS` — resolve hostname once and cache
|
||||
- `STRICT_DNS` — resolve on every connection
|
||||
|
||||
### Secrets (SDS)
|
||||
TLS certificates stored in Envoy's Secret Discovery Service. Aegis manages these automatically when you issue certificates via the Certs page.
|
||||
|
||||
## Common setups
|
||||
|
||||
### Reverse proxy for a single service
|
||||
|
||||
1. Create a cluster pointing to your service (e.g. `192.168.1.10:3000`)
|
||||
2. Add an HTTPS listener on port 443
|
||||
3. Add a filter chain: domain = `app.example.com`, cluster = your cluster, TLS = your cert
|
||||
|
||||
### Multiple domains on one server
|
||||
|
||||
Add one filter chain per domain to your HTTPS listener. Each filter chain has its own SNI match, backend cluster, and TLS secret.
|
||||
|
||||
### HTTP → HTTPS redirect
|
||||
|
||||
Add a catch-all filter chain on the port-80 listener with a Lua HTTP filter that returns a 301 redirect.
|
||||
|
||||
## Blocked IPs
|
||||
|
||||
Blocked IPs are automatically injected as Envoy RBAC deny rules on every xDS push. You do not need to configure this.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"xDS NACK"** in the dashboard header means Envoy rejected the last config. The error message shows which resource failed. Fix the highlighted resource and save again.
|
||||
|
||||
**Changes not applying** — check that the xDS status is "synced" (green dot). If it shows "xDS …" (grey), Envoy is not connected — verify the `NODE_ID` env var matches the node ID in your bootstrap config.
|
||||
Once imported, Aegis dynamically translates these into Envoy-native config and pushes them to Envoy over the xDS channel.
|
||||
|
||||
+22
-25
@@ -9,9 +9,19 @@
|
||||
|
||||
## 1. Download the starter files
|
||||
|
||||
Create a new directory for Aegis and download the required configuration files:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
@@ -20,39 +30,26 @@ curl -o configs/starter.json https://raw.githubusercontent.com/axieyangb/aegis/m
|
||||
|
||||
Edit `docker-compose.yml` and change `ADMIN_PASSWORD=changeme` to something secure.
|
||||
|
||||
## 3. Start
|
||||
## 3. Start the gateway
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Aegis dashboard: `http://localhost:8765`
|
||||
Default login: `admin` / (your password)
|
||||
* Aegis dashboard: `http://localhost:8765`
|
||||
* Default login: `admin` / (your password)
|
||||
|
||||
## 4. Connect Envoy to Aegis
|
||||
## 4. Connect Envoy to Aegis (Importing baseline)
|
||||
|
||||
The starter config in `configs/starter.json` already points Envoy's xDS endpoint at `aegis:18000`. Envoy will connect automatically once both containers are running.
|
||||
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.
|
||||
|
||||
Open **Gateway** in the dashboard — you should see "xDS synced" in green.
|
||||
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.
|
||||
|
||||
## 5. Add your first listener
|
||||
You should see **"xDS synced"** in green on the Gateway page, confirming Envoy has successfully connected and loaded the configuration!
|
||||
|
||||
Go to **Gateway → Listeners → Add filter chain**. Configure your domain, backend cluster, and TLS secret. Changes push to Envoy immediately.
|
||||
## 5. Add your first service
|
||||
|
||||
## 6. Issue a TLS certificate
|
||||
|
||||
Go to **Certificates → Add Provider** and configure an ACME provider (Let's Encrypt + HTTP-01 is the easiest). Then **Issue Certificate** for your domain.
|
||||
|
||||
> **Note:** HTTP-01 requires the `acme-renewer` cluster and a port-80 filter chain. Open the Owl chat and say "Help me set up HTTP-01" — it will walk you through the gateway configuration.
|
||||
|
||||
## 7. Enable AI (optional)
|
||||
|
||||
Go to **Settings → AI**, enable Intelligence Review, and enter an API key for your chosen provider (Gemini, Claude, OpenAI, DeepSeek, or Ollama for local inference). Aegis will start classifying IPs in the background.
|
||||
|
||||
Enable **Owl Chat** to talk to your gateway in natural language.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Envoy configuration reference](envoy-config.md)
|
||||
- [AI setup](ai-setup.md)
|
||||
- [Notifications](notifications.md)
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
node:
|
||||
id: home
|
||||
cluster: aegis
|
||||
|
||||
# All dynamic resources (listeners, clusters, secrets) come from Aegis via ADS.
|
||||
dynamic_resources:
|
||||
ads_config:
|
||||
api_type: GRPC
|
||||
transport_api_version: V3
|
||||
grpc_services:
|
||||
- envoy_grpc:
|
||||
cluster_name: xds_cluster
|
||||
lds_config:
|
||||
resource_api_version: V3
|
||||
ads: {}
|
||||
cds_config:
|
||||
resource_api_version: V3
|
||||
ads: {}
|
||||
|
||||
static_resources:
|
||||
clusters:
|
||||
# xds_cluster is the only static cluster — used for both xDS and ALS gRPC to Aegis.
|
||||
- name: xds_cluster
|
||||
type: STRICT_DNS
|
||||
connect_timeout: 5s
|
||||
typed_extension_protocol_options:
|
||||
envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
|
||||
"@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
|
||||
explicit_http_config:
|
||||
http2_protocol_options: {}
|
||||
load_assignment:
|
||||
cluster_name: xds_cluster
|
||||
endpoints:
|
||||
- lb_endpoints:
|
||||
- endpoint:
|
||||
address:
|
||||
socket_address:
|
||||
address: aegis
|
||||
port_value: 18000
|
||||
|
||||
admin:
|
||||
address:
|
||||
socket_address:
|
||||
address: 0.0.0.0
|
||||
port_value: 9901
|
||||
access_log:
|
||||
- name: envoy.access_loggers.file
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
|
||||
path: /dev/null
|
||||
Reference in New Issue
Block a user