puffin-app/DNS_TROUBLESHOOTING.md

# DNS Troubleshooting Guide for Puffin Backend

## Current Issue
Backend container cannot resolve `api.wren.co` despite DNS servers (8.8.8.8, 8.8.4.4) configured in docker-compose.yml.

## Diagnostic Steps

### 1. Verify DNS Config in Running Container
```bash
docker exec puffin-backend cat /etc/resolv.conf
```
**Expected**: Should show `nameserver 8.8.8.8` and `nameserver 8.8.4.4`
**If not**: Container wasn't recreated properly

### 2. Test DNS Resolution from Container
```bash
# Test with nslookup (if available)
docker exec puffin-backend nslookup api.wren.co

# Test with getent (usually available)
docker exec puffin-backend getent hosts api.wren.co

# Test with wget
docker exec puffin-backend wget -O- --timeout=5 https://api.wren.co/v1/offset_orders 2>&1 | head -20
```

### 3. Check if Host Can Resolve DNS
```bash
# On the host machine
nslookup api.wren.co
ping api.wren.co
```
**If host can't resolve**: Host DNS issue, not Docker issue

### 4. Check Docker Daemon DNS Configuration
```bash
# Check Docker daemon config
cat /etc/docker/daemon.json

# Check Docker network DNS
docker network inspect puffin-network | grep -A 5 "IPAM"
```

### 5. Test with Different DNS Servers
Try Cloudflare DNS instead of Google:
```yaml
dns:
  - 1.1.1.1
  - 1.0.0.1
```

### 6. Check Firewall Rules
```bash
# Check if firewall is blocking DNS from containers
sudo iptables -L -n | grep -i dns
sudo ufw status verbose

# Temporarily disable firewall to test (BE CAREFUL)
sudo ufw disable
# Test, then re-enable:
sudo ufw enable
```

### 7. Check Docker Network Isolation
```bash
# Check if Docker bridge has internet access
docker run --rm busybox ping -c 3 8.8.8.8
docker run --rm busybox nslookup api.wren.co 8.8.8.8
```

## Solutions to Try

### Solution 1: Use Host Network Mode (Testing Only)
**WARNING**: Less secure, only for testing
```yaml
backend:
  network_mode: "host"
  # Remove 'networks' and 'ports' when using host mode
```

### Solution 2: Update Docker Daemon DNS
Edit `/etc/docker/daemon.json`:
```json
{
  "dns": ["8.8.8.8", "8.8.4.4"]
}
```
Then restart Docker:
```bash
sudo systemctl restart docker
```

### Solution 3: Use Host's DNS Resolver
```yaml
backend:
  dns:
    - 8.8.8.8
    - 8.8.4.4
  extra_hosts:
    - "api.wren.co:HOST_IP_HERE"
```

### Solution 4: Disable Docker's Userland Proxy
Edit `/etc/docker/daemon.json`:
```json
{
  "userland-proxy": false,
  "dns": ["8.8.8.8", "8.8.4.4"]
}
```

### Solution 5: Force Recreate with Network Cleanup
```bash
# Stop everything
docker-compose down

# Remove network
docker network rm puffin-network

# Recreate with proper DNS
docker-compose up -d --force-recreate
```

## Current Status
- ✅ DNS servers added to docker-compose.yml (8.8.8.8, 8.8.4.4)
- ✅ Stripe webhooks working (proves network connectivity works)
- ❌ DNS resolution failing with ENOTFOUND api.wren.co
- ❌ Error occurs after only 26ms (DNS query not reaching nameservers)

## Next Actions
1. Run diagnostic commands above to identify exact failure point
2. Check if issue is container-specific or host-wide
3. Apply appropriate solution based on findings