gitrepublic-web/k8s/README.md

Kubernetes Deployment Guide

This directory contains Kubernetes manifests for enterprise-grade multi-tenant deployment of gitrepublic-web.

Architecture

Enterprise Mode (Kubernetes)

• Container-per-tenant: Each user (npub) gets their own namespace
• Process isolation: Complete isolation between tenants
• Network isolation: Network policies prevent inter-tenant communication
• Resource quotas: Per-tenant CPU, memory, and storage limits
• Separate volumes: Each tenant has their own PersistentVolume

Lightweight Mode (Single Container)

• Application-level security controls
• Works with current Docker setup
• See ../docs/SECURITY_IMPLEMENTATION.md for details

Directory Structure

k8s/
├── base/                    # Base Kubernetes manifests (templates)
│   ├── namespace.yaml      # Namespace per tenant
│   ├── resource-quota.yaml # Resource limits per tenant
│   ├── limit-range.yaml    # Default container limits
│   ├── deployment.yaml     # Application deployment
│   ├── service.yaml        # Service definition
│   ├── pvc.yaml            # Persistent volume claim
│   └── network-policy.yaml # Network isolation
├── overlays/
│   ├── single-container/   # Single container setup (lightweight)
│   └── multi-tenant/       # Kubernetes setup (enterprise)
└── README.md               # This file

Usage

Single Container (Lightweight) - Default Mode

Use the existing docker-compose.yml or Dockerfile. Security improvements are application-level and work automatically.

Environment Variable: ENTERPRISE_MODE is not set (defaults to false)

Kubernetes (Enterprise Mode)

Enable Enterprise Mode: Set ENTERPRISE_MODE=true environment variable

Enterprise mode provides:

• Container-per-tenant isolation
• Separate volumes per tenant
• Network isolation
• Resource quotas
• Process isolation

Option 1: Using Deployment Script (Recommended)

Use the provided deployment script:

# Deploy a tenant
./k8s/deploy-tenant.sh npub1abc123... \
  --domain git.example.com \
  --storage-class fast-ssd \
  --storage-size 50Gi \
  --subdomain user1

# Delete a tenant
./k8s/delete-tenant.sh npub1abc123...

Option 2: Manual Deployment

1. Create namespace for tenant:

export TENANT_ID="npub1abc123..."
export GIT_DOMAIN="git.example.com"
export NOSTR_RELAYS="wss://relay1.com,wss://relay2.com"
export STORAGE_CLASS="fast-ssd"
export STORAGE_SIZE="100Gi"
export TENANT_SUBDOMAIN="user1"

# Replace variables in templates
envsubst < k8s/base/namespace.yaml | kubectl apply -f -
envsubst < k8s/base/resource-quota.yaml | kubectl apply -f -
envsubst < k8s/base/limit-range.yaml | kubectl apply -f -
envsubst < k8s/base/pvc.yaml | kubectl apply -f -
envsubst < k8s/base/deployment.yaml | kubectl apply -f -
envsubst < k8s/base/service.yaml | kubectl apply -f -
envsubst < k8s/base/network-policy.yaml | kubectl apply -f -
envsubst < k8s/base/ingress.yaml | kubectl apply -f -

Option 3: Operator Pattern (Advanced)

Create a Kubernetes operator that:

• Watches for new repository announcements
• Automatically creates namespaces for new tenants
• Manages tenant lifecycle
• Handles scaling and resource allocation

Option 4: Helm Chart

Package as Helm chart for easier deployment:

helm install gitrepublic ./helm-chart \
  --set tenant.id=npub1abc123... \
  --set git.domain=git.example.com

Configuration

Environment Variables

Variable	Description	Default
SECURITY_MODE	lightweight or enterprise	lightweight
MAX_REPOS_PER_USER	Max repos per user	100
MAX_DISK_QUOTA_PER_USER	Max disk per user (bytes)	10737418240 (10GB)
RATE_LIMIT_ENABLED	Enable rate limiting	true
AUDIT_LOGGING_ENABLED	Enable audit logging	true

Resource Quotas

Adjust in resource-quota.yaml:

• CPU: requests/limits per tenant
• Memory: requests/limits per tenant
• Storage: per-tenant volume size
• Pods: max pods per tenant

Ingress Configuration

Use an Ingress controller (e.g., nginx-ingress) to route traffic:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: gitrepublic-ingress
  namespace: gitrepublic-tenant-${TENANT_ID}
spec:
  ingressClassName: nginx
  rules:
  - host: ${TENANT_SUBDOMAIN}.git.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: gitrepublic
            port:
              number: 80

Monitoring

Recommended Tools

• Prometheus: Metrics collection
• Grafana: Dashboards
• Loki: Log aggregation
• Jaeger: Distributed tracing

Metrics to Monitor

• Request rate per tenant
• Resource usage per tenant
• Error rates
• Git operation durations
• Disk usage per tenant

Backup Strategy

Per-Tenant Backups

1. Volume Snapshots: Use Kubernetes VolumeSnapshots
2. Git Repo Backups: Regular git bundle exports
3. Metadata Backups: Export Nostr events

Example Backup Job

apiVersion: batch/v1
kind: CronJob
metadata:
  name: gitrepublic-backup
  namespace: gitrepublic-tenant-${TENANT_ID}
spec:
  schedule: "0 2 * * *"  # Daily at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: gitrepublic-backup:latest
            command: ["/backup.sh"]
            volumeMounts:
            - name: repos
              mountPath: /repos
          volumes:
          - name: repos
            persistentVolumeClaim:
              claimName: gitrepublic-repos

Migration from Lightweight to Enterprise

1. Export tenant data: Backup repositories
2. Create namespace: Set up K8s resources
3. Import data: Restore to new volume
4. Update DNS: Point to new service
5. Verify: Test all operations
6. Decommission: Remove old container

Security Considerations

Network Policies

• Prevents inter-tenant communication
• Restricts egress to necessary services only
• Allows ingress from ingress controller only

Resource Quotas

• Prevents resource exhaustion
• Ensures fair resource allocation
• Limits blast radius of issues

Process Isolation

• Complete isolation between tenants
• No shared memory or filesystem
• Separate security contexts

Cost Considerations

Lightweight Mode

• Lower cost: Single container, shared resources
• Lower isolation: Application-level only
• Good for: Small to medium deployments

Enterprise Mode

• Higher cost: Multiple containers, separate volumes
• Higher isolation: Process and network isolation
• Good for: Large deployments, enterprise customers

Hybrid Approach

Run both modes:

• Lightweight: For most users (cost-effective)
• Enterprise: For high-value tenants (isolation)

Use a tenant classification system to route tenants to appropriate mode.