init: Initial commit

2026-02-05 18:37:35 +01:00
commit 31f5b4081a
25 changed files with 1759 additions and 0 deletions
--- a/.docs/deployment.md
+++ b/.docs/deployment.md
@@ -0,0 +1,267 @@
+# Deployment
+
+## Docker Deployment
+
+### Using Docker Compose (Recommended)
+
+```bash
+docker compose up -d
+```
+
+This will:
+1. Pull the image `git.secnex.io/secnex/api-gateway:latest`
+2. Build locally if the image cannot be pulled
+3. Start the gateway on port 8080
+
+### Manual Docker Build
+
+```bash
+# Build the image
+docker build -t secnex-gateway .
+
+# Run the container
+docker run -d \
+  -p 8080:8080 \
+  -v $(pwd)/gateway.yaml:/app/gateway.yaml:ro \
+  --name gateway \
+  secnex-gateway
+```
+
+### Docker Image from Registry
+
+```bash
+docker pull git.secnex.io/secnex/api-gateway:latest
+docker run -d \
+  -p 8080:8080 \
+  -v $(pwd)/gateway.yaml:/app/gateway.yaml:ro \
+  --name gateway \
+  git.secnex.io/secnex/api-gateway:latest
+```
+
+## Configuration Management
+
+### Production Configuration
+
+Create a production-specific `gateway.yaml`:
+
+```yaml
+gateway:
+  host: "0.0.0.0"
+  port: 8080
+  features:
+    - request_id
+    - real_ip
+    - logger
+
+# ... rest of configuration
+```
+
+### Environment-Specific Configs
+
+Use multiple config files:
+
+```bash
+# Development
+docker run -v $(pwd)/gateway.dev.yaml:/app/gateway.yaml ...
+
+# Production
+docker run -v $(pwd)/gateway.prod.yaml:/app/gateway.yaml ...
+```
+
+## Kubernetes Deployment
+
+### Deployment Manifest
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-gateway
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: api-gateway
+  template:
+    metadata:
+      labels:
+        app: api-gateway
+    spec:
+      containers:
+      - name: gateway
+        image: git.secnex.io/secnex/api-gateway:latest
+        ports:
+        - containerPort: 8080
+        volumeMounts:
+        - name: config
+          mountPath: /app/gateway.yaml
+          subPath: gateway.yaml
+        resources:
+          requests:
+            memory: "128Mi"
+            cpu: "100m"
+          limits:
+            memory: "256Mi"
+            cpu: "500m"
+      volumes:
+      - name: config
+        configMap:
+          name: gateway-config
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: gateway-config
+data:
+  gateway.yaml: |
+    gateway:
+      host: "0.0.0.0"
+      port: 8080
+      features:
+        - request_id
+        - real_ip
+        - logger
+    # ... rest of configuration
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: api-gateway
+spec:
+  selector:
+    app: api-gateway
+  ports:
+  - port: 80
+    targetPort: 8080
+  type: LoadBalancer
+```
+
+### Apply to Kubernetes
+
+```bash
+kubectl apply -f k8s-deployment.yaml
+```
+
+## Health Checks
+
+The gateway provides a health check endpoint:
+
+```bash
+curl http://localhost:8080/_/health
+```
+
+### Kubernetes Liveness/Readiness Probes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /_/health
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /_/health
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 5
+```
+
+## Reverse Proxy Setup
+
+### Nginx Reverse Proxy
+
+```nginx
+upstream gateway {
+    server localhost:8080;
+}
+
+server {
+    listen 80;
+    server_name api.example.com;
+
+    location / {
+        proxy_pass http://gateway;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Monitoring
+
+### Log Collection
+
+Logs are output in JSON format. Configure your log collector:
+
+**Fluentd example:**
+```xml
+<source>
+  @type tail
+  path /var/log/containers/gateway*.log
+  pos_file /var/log/gateway.log.pos
+  tag gateway.*
+  <parse>
+    @type json
+  </parse>
+</source>
+```
+
+### Metrics
+
+Consider adding Prometheus metrics for production deployments:
+- Request count by route
+- Response time histograms
+- Error rates
+- Backend connection status
+
+## Security Considerations
+
+### Production Checklist
+
+- [ ] Use TLS/HTTPS in production
+- [ ] Restrict gateway configuration file permissions
+- [ ] Use secrets management for API keys
+- [ ] Enable rate limiting
+- [ ] Configure WAF rules appropriately
+- [ ] Regular security updates
+- [ ] Log monitoring and alerting
+- [ ] Backup configuration files
+
+### TLS Termination
+
+Options for TLS:
+1. **At the gateway** - Configure Go server with TLS
+2. **At reverse proxy** - Use Nginx/HAProxy with TLS
+3. **At cloud load balancer** - Use AWS ALB, GCP LB, etc.
+
+## Scaling
+
+### Horizontal Scaling
+
+Run multiple instances behind a load balancer:
+
+```yaml
+# docker-compose.yml
+services:
+  gateway:
+    deploy:
+      replicas: 3
+```
+
+### Resource Limits
+
+Configure appropriate resource limits:
+
+```yaml
+resources:
+  limits:
+    memory: "512Mi"
+    cpu: "1000m"
+  reservations:
+    memory: "256Mi"
+    cpu: "500m"
+```