Domain Configuration

Configure custom domains, subdomains, and DNS settings for your nself deployment with support for multiple domains and SSL certificates.

Domain Setup

Single Domain Configuration

# In .env.local or production .env:
DOMAIN=yourdomain.com
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@yourdomain.com

# Rebuild and start
nself build && nself up

Multiple Domains

# Primary domain
DOMAIN=yourdomain.com

# Additional domains (comma-separated)
ADDITIONAL_DOMAINS=www.yourdomain.com,app.yourdomain.com,api.yourdomain.com

# All domains will get SSL certificates automatically

DNS Configuration

Required DNS Records

Set up these DNS records with your domain provider:

A Records

# Point your domain to your server IP
yourdomain.com.        A    203.0.113.1
www.yourdomain.com.    A    203.0.113.1
api.yourdomain.com.    A    203.0.113.1
app.yourdomain.com.    A    203.0.113.1

CNAME Records (Alternative)

# If using a CNAME to point to another domain
www.yourdomain.com.    CNAME    yourdomain.com.
api.yourdomain.com.    CNAME    yourdomain.com.

Subdomain Configuration

Service-Specific Subdomains

# Configure specific services on subdomains
HASURA_SUBDOMAIN=api         # api.yourdomain.com
MINIO_SUBDOMAIN=storage      # storage.yourdomain.com  
GRAFANA_SUBDOMAIN=monitoring # monitoring.yourdomain.com
ADMINER_SUBDOMAIN=db         # db.yourdomain.com

# These require corresponding DNS A records

Wildcard DNS

# Use wildcard DNS for dynamic subdomains
*.yourdomain.com.    A    203.0.113.1

# Enable wildcard support
WILDCARD_ENABLED=true
WILDCARD_SSL=true

Local Development Domains

Development Domains

# For local development
DOMAIN=local.nself.org
DEVELOPMENT_MODE=true

# nself provides these local domains automatically:
# - http://localhost:8080 (Hasura)
# - http://localhost:9001 (MinIO Console)
# - http://localhost:5432 (PostgreSQL)
# - http://localhost:6379 (Redis)

# Or use custom local domains:
DOMAIN=myapp.local
# Add to /etc/hosts: 127.0.0.1 myapp.local

Hosts File Configuration

# Add to /etc/hosts for local development
127.0.0.1 myapp.local
127.0.0.1 api.myapp.local
127.0.0.1 storage.myapp.local
127.0.0.1 admin.myapp.local

Load Balancer Configuration

Behind a Load Balancer

# If running behind AWS ALB, CloudFlare, etc.
BEHIND_LOAD_BALANCER=true
TRUST_PROXY=true
PROXY_PROTOCOL_ENABLED=true

# Trust these proxy IPs
TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

# Forward headers
FORWARDED_HEADERS_ENABLED=true

CDN Configuration

# When using a CDN (CloudFlare, AWS CloudFront)
CDN_ENABLED=true
CDN_PROVIDER=cloudflare

# Origin server settings
ORIGIN_ONLY_ACCESS=true
ORIGIN_SECRET=your-origin-secret

# Real visitor IP headers
REAL_IP_HEADER=CF-Connecting-IP
CLOUDFLARE_IPS_ENABLED=true

Custom Domain Routing

Service-Specific Routing

# Route different services to different domains
HASURA_DOMAIN=api.yourdomain.com
MINIO_DOMAIN=storage.yourdomain.com
GRAFANA_DOMAIN=monitoring.yourdomain.com
FRONTEND_DOMAIN=app.yourdomain.com

# Custom routing rules
CUSTOM_ROUTES_ENABLED=true

Path-Based Routing

# Route by path instead of subdomain
# yourdomain.com/api -> Hasura
# yourdomain.com/storage -> MinIO
# yourdomain.com/monitoring -> Grafana

PATH_BASED_ROUTING=true
API_PATH=/api/v1
STORAGE_PATH=/storage
MONITORING_PATH=/monitoring

Domain Validation

DNS Propagation Check

# Check DNS propagation
dig yourdomain.com A
nslookup yourdomain.com
host yourdomain.com

# Test from multiple locations
dig @8.8.8.8 yourdomain.com
dig @1.1.1.1 yourdomain.com

# Check SSL certificate for domain
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

Domain Validation Commands

# nself domain validation
nself domain verify yourdomain.com
nself domain test-ssl yourdomain.com
nself domain check-dns yourdomain.com

Multi-Tenant Domain Setup

Customer Subdomains

# Enable customer subdomains
MULTI_TENANT_ENABLED=true
TENANT_SUBDOMAIN_PATTERN=*.yourdomain.com

# Each tenant gets their own subdomain:
# customer1.yourdomain.com
# customer2.yourdomain.com
# etc.

# Database isolation per tenant
TENANT_DATABASE_STRATEGY=schema  # or 'database'

Custom Customer Domains

# Allow customers to use their own domains
CUSTOM_DOMAINS_ENABLED=true
CUSTOM_DOMAIN_VERIFICATION=dns  # or 'file'

# Customer points customer.com -> your-server-ip
# You configure:
CUSTOM_DOMAIN_customer_com=customer123

# SSL certificates automatically provisioned

Domain Security

Domain Security Headers

# Prevent domain-related attacks
DOMAIN_SECURITY_ENABLED=true

# HSTS for all domains
HSTS_ALL_DOMAINS=true
HSTS_INCLUDE_SUBDOMAINS=true

# Content Security Policy
CSP_FRAME_ANCESTORS='self'
CSP_CONNECT_SRC='self https://*.yourdomain.com'

# Referrer policy
REFERRER_POLICY=strict-origin-when-cross-origin

Domain Validation

# Validate allowed domains
ALLOWED_DOMAINS=yourdomain.com,www.yourdomain.com
BLOCK_UNKNOWN_DOMAINS=true

# CORS configuration per domain
CORS_ORIGINS=https://yourdomain.com,https://www.yourdomain.com,https://app.yourdomain.com

Development vs Production Domains

Environment-Specific Configuration

# Development (.env.local)
DOMAIN=local.nself.org
ENVIRONMENT=development
SSL_MODE=self-signed

# Staging (.env.staging)
DOMAIN=staging.yourdomain.com
ENVIRONMENT=staging
SSL_MODE=letsencrypt
SSL_STAGING=true

# Production (.env)
DOMAIN=yourdomain.com
ENVIRONMENT=production
SSL_MODE=letsencrypt
SSL_STAGING=false

Troubleshooting Domain Issues

Common Domain Problems

DNS Not Propagating

# Check DNS propagation globally
dig +trace yourdomain.com

# Test specific DNS servers
dig @8.8.8.8 yourdomain.com  # Google
dig @1.1.1.1 yourdomain.com  # Cloudflare
dig @208.67.222.222 yourdomain.com  # OpenDNS

# Clear local DNS cache
sudo dscacheutil -flushcache  # macOS
sudo systemctl restart systemd-resolved  # Ubuntu

SSL Certificate Issues

# Check if domain is accessible
curl -I https://yourdomain.com

# Verify SSL certificate
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

# Check certificate details
echo | openssl s_client -connect yourdomain.com:443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -dates

Subdomain Not Working

# Verify subdomain DNS record
dig api.yourdomain.com

# Check nginx configuration
nself exec nginx nginx -t

# View nginx access logs
nself logs nginx | grep api.yourdomain.com

# Test subdomain directly
curl -H "Host: api.yourdomain.com" http://your-server-ip/

Domain Migration

Changing Domains

# Update domain configuration
# 1. Update .env file
DOMAIN=newdomain.com

# 2. Update DNS records for new domain
# 3. Rebuild with new configuration
nself build

# 4. Update SSL certificates
nself ssl renew

# 5. Test new domain
curl -I https://newdomain.com

Domain Redirects

# Redirect old domain to new domain
DOMAIN_REDIRECTS_ENABLED=true
REDIRECT_olddomain_com=https://newdomain.com

# Permanent redirects (301)
REDIRECT_TYPE=permanent

# Temporary redirects (302)
REDIRECT_TYPE=temporary

Best Practices

  • Use HTTPS everywhere: Enable SSL for all domains
  • Plan subdomains: Use consistent subdomain patterns
  • Monitor DNS: Set up monitoring for DNS changes
  • Document configuration: Keep domain configuration documented
  • Test thoroughly: Test all domains and subdomains after changes
  • Use staging domains: Test changes on staging before production
  • Backup DNS: Export DNS records regularly
  • Monitor certificates: Set up alerts for certificate expiration

Next Steps