puffin-app/DNS_TROUBLESHOOTING.md
Matt 7bdd462be9
Some checks failed
Build and Push Docker Images / docker (push) Has been cancelled
Implement comprehensive email templates with SMTP integration
- Add beautiful HTML email templates for receipts, admin notifications, and contact forms
- Implement SMTP email service with Nodemailer and Handlebars templating
- Add carbon equivalency calculations with EPA/DEFRA/IMO 2024 conversion factors
- Add portfolio color palette system for project visualization
- Integrate Wren API portfolio fetching in webhook handler
- Add light mode enforcement for email client compatibility
- Include Puffin logo from MinIO S3 in all templates
- Add test email endpoint for template validation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-31 20:09:31 +01:00

3.0 KiB

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

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

# 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

# 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

# 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:

dns:
  - 1.1.1.1
  - 1.0.0.1

6. Check Firewall Rules

# 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

# 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

backend:
  network_mode: "host"
  # Remove 'networks' and 'ports' when using host mode

Solution 2: Update Docker Daemon DNS

Edit /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Then restart Docker:

sudo systemctl restart docker

Solution 3: Use Host's DNS Resolver

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:

{
  "userland-proxy": false,
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Solution 5: Force Recreate with Network Cleanup

# 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