dbis_core/CLOUDFLARE_DNS_CONFIGURATION.md

# DBIS Core - Cloudflare DNS Configuration

## Overview

This document provides recommended Cloudflare DNS entries for the DBIS Core Banking System containers deployed on Proxmox VE.

## Architecture

```
Internet → Cloudflare DNS → Cloudflare Tunnel → cloudflared LXC → DBIS Core Containers
```

## Container Summary

| Service | VMID | IP Address | Ports | Public Access |
|---------|------|------------|-------|---------------|
| **Frontend Admin Console** | 10130 | 192.168.11.130 | 80, 443 | ✅ Yes |
| **API Primary** | 10150 | 192.168.11.150 | 3000 | ✅ Yes (or via frontend) |
| **API Secondary** | 10151 | 192.168.11.151 | 3000 | ✅ Yes (HA) |
| **PostgreSQL Primary** | 10100 | 192.168.11.100 | 5432 | ❌ No (Internal only) |
| **PostgreSQL Replica** | 10101 | 192.168.11.101 | 5432 | ❌ No (Internal only) |
| **Redis Cache** | 10120 | 192.168.11.120 | 6379 | ❌ No (Internal only) |

## Recommended DNS Entries

### Primary Public Endpoints

#### 1. Frontend Admin Console
**Purpose**: Main web interface for DBIS Core administration

**DNS Record:**
```
Type: CNAME
Name: dbis-admin
Target: <tunnel-id>.cfargotunnel.com
TTL: Auto
Proxy: 🟠 Proxied (orange cloud)
```

**Full Domain**: `dbis-admin.d-bis.org`

**Tunnel Ingress Configuration:**
```
Subdomain: dbis-admin
Domain: d-bis.org
Service: http://192.168.11.130:80
```

**Alternative Names:**
- `dbis.d-bis.org` (main entry)
- `admin.d-bis.org` (alternative)
- `dbis-console.d-bis.org` (descriptive)

---

#### 2. API Primary Endpoint
**Purpose**: Backend API for DBIS Core services

**DNS Record:**
```
Type: CNAME
Name: dbis-api
Target: <tunnel-id>.cfargotunnel.com
TTL: Auto
Proxy: 🟠 Proxied (orange cloud)
```

**Full Domain**: `dbis-api.d-bis.org`

**Tunnel Ingress Configuration:**
```
Subdomain: dbis-api
Domain: d-bis.org
Service: http://192.168.11.150:3000
```

**Alternative Names:**
- `api.d-bis.org` (if no other API exists)
- `dbis-api-primary.d-bis.org` (descriptive)

---

#### 3. API Secondary Endpoint (High Availability)
**Purpose**: Backup API endpoint for load balancing and failover

**DNS Record:**
```
Type: CNAME
Name: dbis-api-2
Target: <tunnel-id>.cfargotunnel.com
TTL: Auto
Proxy: 🟠 Proxied (orange cloud)
```

**Full Domain**: `dbis-api-2.d-bis.org`

**Tunnel Ingress Configuration:**
```
Subdomain: dbis-api-2
Domain: d-bis.org
Service: http://192.168.11.151:3000
```

**Note**: This can be used for load balancing or as a backup endpoint.

---

### Internal Services (No Public DNS)

**⚠️ DO NOT create public DNS entries for these services:**

- **PostgreSQL** (VMID 10100, 10101) - Database should remain internal
- **Redis** (VMID 10120) - Cache should remain internal

These services should only be accessible from:
- Other containers on the same network (192.168.11.0/24)
- VPN connections
- Direct internal network access

---

## Complete DNS Configuration Table

| Service | Type | Name | Target | Proxy | Purpose |
|---------|------|------|--------|-------|---------|
| **Frontend** | CNAME | `dbis-admin` | `<tunnel-id>.cfargotunnel.com` | 🟠 Proxied | Admin console UI |
| **Frontend (Alt)** | CNAME | `dbis` | `<tunnel-id>.cfargotunnel.com` | 🟠 Proxied | Main entry point |
| **API Primary** | CNAME | `dbis-api` | `<tunnel-id>.cfargotunnel.com` | 🟠 Proxied | Backend API |
| **API Secondary** | CNAME | `dbis-api-2` | `<tunnel-id>.cfargotunnel.com` | 🟠 Proxied | HA backup API |

---

## Tunnel Ingress Configuration

### Complete Ingress Rules

In Cloudflare Zero Trust Dashboard → Networks → Tunnels → Configure:

```yaml
ingress:
  # Frontend Admin Console
  - hostname: dbis-admin.d-bis.org
    service: http://192.168.11.130:80
  
  - hostname: dbis.d-bis.org
    service: http://192.168.11.130:80
  
  # API Primary
  - hostname: dbis-api.d-bis.org
    service: http://192.168.11.150:3000
  
  # API Secondary (HA)
  - hostname: dbis-api-2.d-bis.org
    service: http://192.168.11.151:3000
  
  # Catch-all (404)
  - service: http_status:404
```

---

## SSL/TLS Configuration

### Automatic SSL
Cloudflare automatically provides SSL certificates when:
- ✅ DNS record has proxy enabled (orange cloud)
- ✅ Domain is managed by Cloudflare
- ✅ SSL/TLS mode is set to "Full" or "Full (strict)"

### SSL/TLS Settings
**Recommended**: Full (strict)
- **SSL/TLS encryption mode**: Full (strict)
- **Always Use HTTPS**: On
- **Minimum TLS Version**: TLS 1.2
- **Automatic HTTPS Rewrites**: On

---

## Security Considerations

### 1. Frontend Access
- ✅ Public access via Cloudflare
- ✅ Protected by Cloudflare DDoS protection
- ✅ SSL/TLS encryption
- ⚠️ Consider adding Cloudflare Access (Zero Trust) for additional authentication

### 2. API Access
- ✅ Public access via Cloudflare
- ✅ Protected by Cloudflare DDoS protection
- ✅ SSL/TLS encryption
- ⚠️ **IMPORTANT**: API should have authentication (JWT tokens, API keys)
- ⚠️ Consider rate limiting in Cloudflare

### 3. Database & Cache
- ❌ **NEVER** expose publicly
- ✅ Internal network access only
- ✅ Firewall rules should restrict access

---

## Load Balancing (Optional)

If you want to use Cloudflare Load Balancing for the API endpoints:

### 1. Create Load Balancer Pool
```
Pool Name: dbis-api-pool
Origin Servers:
  - dbis-api.d-bis.org (Primary)
  - dbis-api-2.d-bis.org (Secondary)
Health Check: HTTP GET /health
```

### 2. Create Load Balancer
```
Name: dbis-api-lb
Hostname: api.d-bis.org
Pool: dbis-api-pool
TTL: 30 seconds
```

### 3. DNS Record
```
Type: CNAME
Name: api
Target: dbis-api-lb.d-bis.org
Proxy: 🟠 Proxied
```

---

## Health Check Endpoints

### API Health Check
**Endpoint**: `https://dbis-api.d-bis.org/health`

**Expected Response:**
```json
{
  "status": "healthy",
  "database": "connected",
  "redis": "connected",
  "timestamp": "2025-12-26T01:00:00Z"
}
```

### Frontend Health Check
**Endpoint**: `https://dbis-admin.d-bis.org/health`

**Expected Response:**
```
healthy
```

---

## Testing DNS Configuration

### 1. Verify DNS Resolution
```bash
# Test DNS resolution
dig dbis-admin.d-bis.org
nslookup dbis-admin.d-bis.org

# Should resolve to Cloudflare IPs (if proxied)
```

### 2. Test HTTPS Access
```bash
# Test frontend
curl -I https://dbis-admin.d-bis.org

# Test API
curl -I https://dbis-api.d-bis.org/health
```

### 3. Test Tunnel Connection
```bash
# Check tunnel status in Cloudflare dashboard
# Zero Trust → Networks → Tunnels → Status should be "Healthy"
```

---

## Step-by-Step Setup

### Step 1: Create DNS Records in Cloudflare

1. **Navigate to Cloudflare Dashboard**
   - Go to your domain (d-bis.org)
   - Click **DNS** → **Records**

2. **Add Frontend Record**
   - Click **Add record**
   - **Type**: CNAME
   - **Name**: `dbis-admin`
   - **Target**: `<your-tunnel-id>.cfargotunnel.com`
   - **Proxy status**: 🟠 Proxied
   - Click **Save**

3. **Add API Primary Record**
   - Click **Add record**
   - **Type**: CNAME
   - **Name**: `dbis-api`
   - **Target**: `<your-tunnel-id>.cfargotunnel.com`
   - **Proxy status**: 🟠 Proxied
   - Click **Save**

4. **Add API Secondary Record** (Optional)
   - Click **Add record**
   - **Type**: CNAME
   - **Name**: `dbis-api-2`
   - **Target**: `<your-tunnel-id>.cfargotunnel.com`
   - **Proxy status**: 🟠 Proxied
   - Click **Save**

### Step 2: Configure Tunnel Ingress

1. **Navigate to Cloudflare Zero Trust**
   - Go to **Zero Trust** → **Networks** → **Tunnels**
   - Click on your tunnel
   - Click **Configure**

2. **Add Public Hostnames**
   - Click **Public Hostname** tab
   - Add each hostname with corresponding service URL
   - Save configuration

3. **Verify Tunnel Status**
   - Tunnel should show "Healthy" status
   - Check logs for any errors

### Step 3: Verify Configuration

1. **Test DNS Resolution**
   ```bash
   dig dbis-admin.d-bis.org
   ```

2. **Test HTTPS Access**
   ```bash
   curl -I https://dbis-admin.d-bis.org
   ```

3. **Test API Health**
   ```bash
   curl https://dbis-api.d-bis.org/health
   ```

---

## Alternative Configurations

### Option 1: Single Domain with Path Routing
If you prefer a single domain with path-based routing:

**DNS Record:**
```
Type: CNAME
Name: dbis
Target: <tunnel-id>.cfargotunnel.com
Proxy: 🟠 Proxied
```

**Tunnel Ingress:**
```yaml
ingress:
  - hostname: dbis.d-bis.org
    path: /api
    service: http://192.168.11.150:3000
  
  - hostname: dbis.d-bis.org
    service: http://192.168.11.130:80
```

**Access:**
- Frontend: `https://dbis.d-bis.org`
- API: `https://dbis.d-bis.org/api`

### Option 2: Subdomain with API Proxy
Frontend proxies API requests:

**DNS Records:**
- `dbis.d-bis.org` → Frontend (192.168.11.130:80)
- No separate API DNS entry needed

**Frontend Configuration:**
- Nginx configured to proxy `/api/*` to `http://192.168.11.150:3000`
- All requests go through frontend

---

## Monitoring & Maintenance

### DNS Health Checks
- Monitor DNS resolution: `dig dbis-admin.d-bis.org`
- Monitor SSL certificate status in Cloudflare dashboard
- Monitor tunnel health in Zero Trust dashboard

### Performance Monitoring
- Use Cloudflare Analytics to monitor traffic
- Set up alerts for high error rates
- Monitor API response times

### Security Monitoring
- Review Cloudflare Security Events
- Monitor for DDoS attacks
- Review access logs

---

## Troubleshooting

### DNS Not Resolving
1. Verify DNS record type is CNAME
2. Verify proxy is enabled (orange cloud)
3. Check target is correct tunnel domain
4. Wait for DNS propagation (up to 5 minutes)

### Tunnel Not Connecting
1. Check tunnel status in Cloudflare dashboard
2. Verify tunnel token is correct
3. Check cloudflared service logs
4. Verify network connectivity

### Container Not Accessible
1. Verify container is running: `pct status 10130`
2. Test direct access: `curl http://192.168.11.130:80`
3. Check tunnel ingress configuration matches DNS
4. Verify firewall allows traffic from cloudflared container

---

## Quick Reference

### DNS Records Summary
```
dbis-admin.d-bis.org  → Frontend (192.168.11.130:80)
dbis-api.d-bis.org    → API Primary (192.168.11.150:3000)
dbis-api-2.d-bis.org  → API Secondary (192.168.11.151:3000)
```

### Health Check URLs
```
https://dbis-admin.d-bis.org/health
https://dbis-api.d-bis.org/health
```

### Internal Services (No DNS)
```
PostgreSQL: 192.168.11.100:5432 (internal only)
Redis: 192.168.11.120:6379 (internal only)
```

---

**Last Updated**: December 26, 2025
**Status**: Ready for Implementation