API Gateway Implementation Guide // APISIX

Browser
  │
  │  HTTPS :443
  ▼
Cloudflare
  ├─ DDoS protection
  ├─ DNS — proxied (orange cloud — hides VPS IP)
  └─ Full strict TLS to origin
  │
  │  HTTPS
  ▼
Caddy on VPS :443
  ├─ TLS termination (auto Let's Encrypt)
  ├─ api.elfatih.net         → APISIX :9080
  ├─ dashboard.elfatih.net   → Authelia forward-auth → APISIX Dashboard :9000
  └─ auth.elfatih.net        → Authelia :9091
  │
  │  HTTP (internal Docker network — proxy)
  ▼
APISIX :9080
  ├─ openid-connect plugin → validates session against Authelia
  ├─ Rate limiting, routing, request transformation
  └─ Routes to upstream services (localhost:PORT)
  │
  │  HTTP (internal only — 127.0.0.1)
  ▼
Upstream Services  (bound to 127.0.0.1:PORT — never exposed directly)

# Run as root or fatih:
sudo usermod -aG docker hermes
# Takes effect on next login

/home/hermes/stack/                 # git repo root
├── .gitignore                      # excludes .env, oidc.key, db.sqlite3, logs, etcd_data
├── tests/
│   ├── test_config.py              # 19 static config/policy tests
│   ├── test_integration.py         # 6 tests — spins up the real stack, isolated project
│   └── docker-compose.test.yml     # isolated compose project for integration tests
├── caddy/
│   ├── Dockerfile
│   ├── Caddyfile                   # live — 4 vhosts (learn/api/auth/dashboard)
│   └── .env                        # ACME_EMAIL, CLOUDFLARE_API_TOKEN
├── learn-site/
│   ├── index.html                  # learn.elfatih.net landing page
│   └── static/                     # guides — this file included
└── api-gateway/
    ├── docker-compose.yml          # apisix, apisix-dashboard, authelia, etcd services
    ├── .env                        # all gateway secrets — gitignored
    ├── apisix/
    │   ├── config.yaml             # APISIX main configuration
    │   ├── dashboard.yaml.template # sed-rendered into conf.yaml at container start
    │   └── etcd_data/              # etcd persistent data (gitignored)
    └── authelia/
        ├── configuration.yml       # Authelia config — client_secret & OIDC key inline
        ├── users.yml               # user database — Argon2id hashed passwords
        ├── oidc.key                # RSA 4096-bit private key (gitignored, unused — key is inline)
        ├── db.sqlite3              # session DB (gitignored)
        └── notification.txt        # filesystem notifier output (gitignored)

networks:
  proxy:
    name: proxy          # keep same network name so other services are unaffected
    driver: bridge
  gateway-internal:
    driver: bridge
    internal: true        # No internet — etcd + apisix internal comms only

etcd:
  image: quay.io/coreos/etcd:v3.5.14
  container_name: etcd
  networks: [gateway-internal]   # Internal only — not reachable from proxy
  environment:
    ETCD_NAME: etcd0
    ETCD_DATA_DIR: /etcd-data
    ETCD_LISTEN_CLIENT_URLS: "http://0.0.0.0:2379"
    ETCD_ADVERTISE_CLIENT_URLS: "http://etcd:2379"
    ETCD_LISTEN_PEER_URLS: "http://0.0.0.0:2380"
    ETCD_INITIAL_ADVERTISE_PEER_URLS: "http://etcd:2380"
    ETCD_INITIAL_CLUSTER: "etcd0=http://etcd:2380"
    ETCD_INITIAL_CLUSTER_STATE: new
    ETCD_INITIAL_CLUSTER_TOKEN: gateway-etcd
  volumes:
    - ./apisix/etcd_data:/etcd-data
  # Port 2379 NOT exposed to host — internal network only

newgrp docker << 'EOF'
docker exec etcd etcdctl endpoint health
EOF
# Expected: 127.0.0.1:2379 is healthy: successfully committed proposal

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host: ["http://etcd:2379"]
    prefix: /apisix
    timeout: 30
  admin:
    enable_admin: true
    admin_listen:
      ip: 0.0.0.0
      port: 9180
    admin_key:
      - name: admin
        key: ${{APISIX_ADMIN_KEY}}    # native env var templating — confirmed working
        role: admin
    # 127.0.0.0/24 covers direct loopback; 172.16.0.0/12 covers Docker's
    # default bridge subnets, since curl from the host gets hairpin-NATed
    # to the bridge gateway IP before it reaches this container.
    allow_admin:
      - 127.0.0.0/24
      - 172.16.0.0/12

apisix:
  node_listen: 9080
  enable_ipv6: false

plugins:
  - openid-connect    # Phase 2 — auth enforcement, not yet applied to routes
  - limit-req         # Phase 3 — rate limiting
  - limit-count
  - cors
  - request-id
  - proxy-rewrite
  - response-rewrite
  - prometheus        # Phase 4 — metrics
  - http-logger       # Phase 4 — access logs
  - redirect
  - echo
  # ... full plugin list in config.yaml

source /home/hermes/stack/api-gateway/.env

curl -s http://127.0.0.1:9180/apisix/admin/routes \
  -H "X-API-KEY: $APISIX_ADMIN_KEY"
# Expected: {"list":[],"total":0}

curl -s -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $APISIX_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ YOUR_ROUTE_CONFIG }'

conf:
  listen:
    host: 0.0.0.0
    port: 9000
  etcd:
    endpoints: [etcd:2379]

authentication:
  secret: __DASHBOARD_SECRET__
  expire_time: 3600
  users:
    - username: admin
      password: __DASHBOARD_PASS__

apisix-dashboard:
  image: apache/apisix-dashboard:3.0.1-alpine
  volumes:
    - ./apisix/dashboard.yaml.template:/usr/local/apisix-dashboard/conf/conf.yaml.template:ro
  env_file:
    - ./.env
  entrypoint: ["sh", "-c"]
  command:
    - >
      sed
      -e "s#__DASHBOARD_SECRET__#$DASHBOARD_SECRET#"
      -e "s#__DASHBOARD_PASS__#$DASHBOARD_PASS#"
      /usr/local/apisix-dashboard/conf/conf.yaml.template
      > /usr/local/apisix-dashboard/conf/conf.yaml
      && exec /usr/local/apisix-dashboard/manager-api

clients:
  - client_id: apisix
    client_name: APISIX Gateway
    client_secret: "<inline plaintext value — see note above>"
    authorization_policy: one_factor
    redirect_uris:
      - https://api.elfatih.net/callback
    scopes: [openid, profile, email, groups]
    userinfo_signed_response_alg: none

newgrp docker << 'EOF'
docker run --rm authelia/authelia:latest \
  authelia crypto hash generate argon2 --password 'YourPassword'
EOF
# Copy the Digest: line into authelia/users.yml

openssl genrsa -out /home/hermes/stack/api-gateway/authelia/oidc.key 4096

# learn.elfatih.net — static site (added, not in original plan)
learn.elfatih.net {
  root * /srv/learn
  file_server
  try_files {path} {path}.html {path}/index.html
  encode gzip
  header {
    X-Content-Type-Options nosniff
    X-Frame-Options SAMEORIGIN
    Referrer-Policy strict-origin-when-cross-origin
    -Server
  }
  log { output file /var/log/caddy/learn-access.log; format json }
}

# api.elfatih.net — APISIX gateway
api.elfatih.net {
  reverse_proxy apisix:9080
  header { -Server }
  log { output file /var/log/caddy/api-access.log; format json }
}

# auth.elfatih.net — Authelia SSO portal
auth.elfatih.net {
  reverse_proxy authelia:9091
  header { -Server }
  log { output file /var/log/caddy/auth-access.log; format json }
}

# dashboard.elfatih.net — APISIX Dashboard, behind Authelia forward-auth
dashboard.elfatih.net {
  forward_auth authelia:9091 {
    uri /api/verify?rd=https://auth.elfatih.net
    copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
  }
  reverse_proxy apisix-dashboard:9000
  header { -Server }
  log { output file /var/log/caddy/dashboard-access.log; format json }
}

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

# Generate a new secret:
openssl rand -hex 32    # For most secrets

1.  Browser → HTTPS GET https://api.elfatih.net/v1/data
2.  Cloudflare — DDoS filter, passes to origin
3.  Caddy :443 — TLS terminated, X-Real-IP injected, passes to APISIX :9080
4.  APISIX — openid-connect plugin checks for Bearer token or session cookie
5a. Token valid → proceed to route matching
5b. No token   → 302 redirect to https://auth.elfatih.net
6.  Authelia — login form → MFA → OIDC token issued
7.  Authelia — 302 redirect back to https://api.elfatih.net/callback
8.  APISIX — validates token, extracts sub/email/roles from claims
9.  APISIX — limit-count check, X-Request-Id injected, route matched
10. APISIX — upstream selected, X-User/X-Email headers injected
11. Upstream service :PORT (127.0.0.1) — handles request
12. Response flows back: Upstream → APISIX → Caddy → Cloudflare → Browser

1.  Browser → dashboard.elfatih.net
2.  Caddy: forward_auth check → authelia:9091/api/verify
3.  No session → redirect to https://auth.elfatih.net (MFA required)
4.  Authenticated → Caddy proxies to apisix-dashboard:9000
5.  Dashboard shows its own login form (second auth layer)
    Two auth layers: Authelia stops internet noise.
    Dashboard login stops lateral movement if Authelia is ever bypassed.

cd /home/hermes/stack/api-gateway
newgrp docker << 'EOF'
docker compose start    # Start all
docker compose stop     # Stop all
EOF

newgrp docker << 'EOF'
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"
EOF

newgrp docker << 'EOF'
docker logs apisix   --tail 50 -f
docker logs authelia --tail 50 -f
docker logs etcd     --tail 20
EOF

newgrp docker << 'EOF'
docker exec etcd etcdctl snapshot save /etcd-data/backup-$(date +%Y%m%d).db
EOF
cp /home/hermes/stack/api-gateway/apisix/etcd_data/backup-*.db ~/backups/

# Generate hash
newgrp docker << 'EOF'
docker run --rm authelia/authelia:latest \
  authelia crypto hash generate argon2 --password 'NewPassword'
EOF

# Append to /home/hermes/stack/api-gateway/authelia/users.yml — Authelia reloads automatically
# newuser:
#   displayname: "New User"
#   password: "$argon2id$..."
#   email: [email protected]
#   groups: [admins]

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

newgrp docker << 'EOF'
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
EOF

newgrp docker << 'EOF'
docker exec etcd etcdctl endpoint health
EOF

newgrp docker << 'EOF'
docker run --rm --network api-gateway_gateway-internal alpine \
  wget -qSO /dev/null http://apisix:9080/ 2>&1 | head -3
EOF

source /home/hermes/stack/api-gateway/.env
newgrp docker << SHELL
docker run --rm --network container:apisix python:3.11-alpine \
  python3 -c "
import urllib.request
req = urllib.request.Request(
  'http://127.0.0.1:9180/apisix/admin/routes',
  headers={'X-API-KEY': '$APISIX_ADMIN_KEY'}
)
print(urllib.request.urlopen(req).read().decode())
"
SHELL

newgrp docker << 'EOF'
docker run --rm --network proxy alpine \
  wget -qO- http://authelia:9091/api/health
EOF

newgrp docker << 'EOF'
docker run --rm --network proxy alpine \
  wget -qSO /dev/null http://apisix-dashboard:9000/ 2>&1 | head -3
EOF

source /home/hermes/stack/api-gateway/.env
curl -s --max-time 3 http://127.0.0.1:9180/apisix/admin/routes \
  -H "X-API-KEY: $APISIX_ADMIN_KEY"

source /home/hermes/stack/api-gateway/.env

# Create a test route
newgrp docker << SHELL
docker run --rm --network container:apisix python:3.11-alpine \
  python3 -c "
import urllib.request, json
data = json.dumps({
  'uri': '/ping',
  'name': 'test-ping',
  'upstream': {'type':'roundrobin','nodes':[{'host':'127.0.0.1','port':9999,'weight':1}]}
}).encode()
req = urllib.request.Request(
  'http://127.0.0.1:9180/apisix/admin/routes/test1',
  data=data, method='PUT',
  headers={'X-API-KEY':'$APISIX_ADMIN_KEY','Content-Type':'application/json'}
)
r = urllib.request.urlopen(req)
print('Create:', r.status)
# Read it back
req2 = urllib.request.Request('http://127.0.0.1:9180/apisix/admin/routes',
  headers={'X-API-KEY':'$APISIX_ADMIN_KEY'})
import json as j; data2 = j.loads(urllib.request.urlopen(req2).read())
print('Routes in etcd:', data2['total'])
# Delete it
req3 = urllib.request.Request('http://127.0.0.1:9180/apisix/admin/routes/test1',
  method='DELETE', headers={'X-API-KEY':'$APISIX_ADMIN_KEY'})
r3 = urllib.request.urlopen(req3)
print('Delete:', r3.status)
"
SHELL

for port in 80 443 9080 9091 9180 2379; do
  result=$(timeout 2 bash -c "echo >/dev/tcp/46.224.236.152/$port" 2>&1 \
    && echo "OPEN" || echo "closed")
  echo "  Port $port: $result"
done

# Run from your local machine
curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \
  http://46.224.236.152/

curl -s -o /dev/null \
  -w "HTTP %{http_code} | TLS: %{ssl_verify_result} | Time: %{time_total}s\n" \
  https://learn.elfatih.net/

# Try to reach Admin API directly from your local machine
curl -s --max-time 5 http://46.224.236.152:9180/apisix/admin/routes

curl -s -o /dev/null -w "HTTP %{http_code}\n" https://auth.elfatih.net/

curl -s -o /dev/null -w "HTTP %{http_code} -> %{redirect_url}\n" \
  https://api.elfatih.net/