Skip to content

Getting Started with Aegis Gateway

This guide walks you through installing Aegis Gateway, logging in for the first time, securing the management interface, and publishing your first service.

What You Need

Before you start, make sure you have:

  • A server or computer with Docker installed.
  • A public domain name pointing at your server if you want browser-trusted certificates.
  • Ports 80, 443, and 8443 available. Port 2222 is only needed if you plan to use reverse tunnels.

[!TIP] You can try Aegis Gateway on your own computer first. Just remember that Let's Encrypt certificates need a public domain name to work, so local-only testing will show a certificate warning unless you use the built-in self-signed certificate.

Installing Aegis Gateway

Aegis Gateway is distributed as a Docker image.

Create a folder on your computer to store the gateway data:

mkdir -p ./aegis-gateway/data

Run the container:

docker run -d \
  --name aegis-gateway \
  -e AEGIS_ADMIN_USERNAME=admin \
  -e AEGIS_ADMIN_PASSWORD='replace-with-strong-password' \
  -e LETSENCRYPT_EMAIL=you@example.com \
  -e LETSENCRYPT_MODE=staging \
  -e NITRITE_DB_PATH=/app/data/proxy_manager.db \
  -v "$(pwd)/aegis-gateway/data:/app/data" \
  -p 80:80 \
  -p 443:443 \
  -p 8443:8443 \
  -p 2222:22 \
  jadaptive/aegis-gateway:latest

[!NOTE] - Port 80 handles certificate validation and redirects visitors to the secure address. - Port 443 is the secure address visitors will use. - Port 8443 is the management dashboard and API. - Port 2222 is the optional SSH tunnel account.

[!IMPORTANT] Always replace replace-with-strong-password with a strong password. This is the only account that can manage the gateway until you add more users.

Important Environment Variables

Aegis Gateway uses a few environment variables to control certificates and the admin account.

Variable Default What It Does
AEGIS_ADMIN_USERNAME admin The username for the management dashboard and API.
AEGIS_ADMIN_PASSWORD change-me-now The password for the management dashboard and API. Always change this.
LETSENCRYPT_EMAIL admin@example.com The email address Let's Encrypt associates with your certificates. Change this to your own address.
LETSENCRYPT_MODE staging Controls which Let's Encrypt server is used. Use staging for testing and production for real certificates.

[!IMPORTANT] LETSENCRYPT_EMAIL is required for issuing certificates. Let's Encrypt will reject requests that do not include a valid email address.

[!CAUTION] The default mode is staging. Staging certificates are not trusted by browsers and are meant for testing. Switch to production only when you are ready to issue real certificates.

Example for Production

When you are ready to issue real certificates, change LETSENCRYPT_MODE to production:

docker run -d \
  --name aegis-gateway \
  -e AEGIS_ADMIN_USERNAME=admin \
  -e AEGIS_ADMIN_PASSWORD='replace-with-strong-password' \
  -e LETSENCRYPT_EMAIL=you@example.com \
  -e LETSENCRYPT_MODE=production \
  -e NITRITE_DB_PATH=/app/data/proxy_manager.db \
  -v "$(pwd)/aegis-gateway/data:/app/data" \
  -p 80:80 \
  -p 443:443 \
  -p 8443:8443 \
  -p 2222:22 \
  jadaptive/aegis-gateway:latest

Opening the Management Interface

Once Aegis Gateway is running, open your browser and go to:

https://your-server-address:8443

[!NOTE] Replace your-server-address with the domain name or IP address of your server.

The first time you visit, your browser may warn you that the certificate is not trusted. This is expected, because the management interface starts with a self-signed certificate. You can proceed past the warning for now. The next section explains how to install a proper certificate.

Log in with the username and password you set during installation.

Securing the Management Interface with a Certificate

The management interface should use a trusted certificate so you and your users do not see browser warnings.

Before You Begin

Make sure:

  • Your server has a public domain name.
  • Port 80 is open and reachable from the internet. Let's Encrypt uses it to verify that you control the domain.
  • You are visiting the management interface using that domain name, not an IP address.

Request a Certificate from the Dashboard

  1. Log in to the management interface.
  2. Look for the warning about the self-signed certificate.
  3. Click the button to request a Let's Encrypt certificate.
  4. Aegis Gateway will ask Let's Encrypt to issue a certificate for the domain you are using.
  5. The application will restart automatically to load the new certificate.

After the restart, refresh your browser. The warning should be gone.

[!NOTE] Automatic renewal is enabled by default. The gateway will check your certificate before it expires and request a new one when needed.

You can also request and manage certificates using the Aegis Gateway API.

Setting Up a Service

A service in Aegis Gateway is a website or application running on another server that you want to expose through the gateway.

Add a Service from the Dashboard

  1. Log in to the management interface.
  2. Go to the Services section.
  3. Click Add Service.
  4. Enter a friendly name, for example My Website.
  5. Enter the public domain name you want visitors to use, for example www.example.com.
  6. Enter the back-end address where the service is actually running, for example http://192.168.1.50:8080.
  7. Save the service.

Aegis Gateway will:

  • Request a certificate for the public domain name.
  • Update its routing configuration.
  • Start sending visitors to your back-end service.

[!NOTE] The gateway checks the health of your back-end service automatically. If the service goes offline, the gateway will mark it as offline and stop routing traffic to it until it comes back.

What Happens Behind the Scenes

When a visitor goes to https://www.example.com, Aegis Gateway:

  1. Terminates the secure connection using the certificate for www.example.com.
  2. Forwards the request to your back-end service.
  3. Returns the response to the visitor.

If your back-end service uses a self-signed certificate, the gateway still accepts it internally, while visitors see a trusted certificate on the public side.

Publishing Services Behind a Firewall with Reverse Tunnels

If your service is on a computer without a public IP address, you can use a reverse tunnel to publish it through Aegis Gateway. See the Reverse Tunnels page for a full walkthrough.

You can add and remove SSH access keys through the dashboard, or automate them with the Aegis Gateway API.

Checking That Everything Is Working

After you add a service, you can check its status in the dashboard:

  • Live means the back-end is reachable and traffic is being routed.
  • Offline means the back-end is not reachable.
  • Disabled means you manually turned the service off.

You can also check gateway health and configuration status using the Aegis Gateway API.

Next Steps

Now that you have Aegis Gateway running, you can:

  • Add more services and domain names.
  • Explore the API to automate service management.
  • Review the logs to understand how traffic is being handled.
  • Adjust health-check and reconcile settings if you need faster or slower detection.

If you run into trouble, check the container logs:

docker logs -f aegis-gateway

Welcome to simpler, safer service publishing.