DynamoDNS/docs/deployment-guide.md

DynamoDNS Deployment Guide

This guide outlines the steps required to deploy and configure DynamoDNS in your environment.

System Requirements

Minimum Requirements

• Node.js: v18.0.0 or higher
• PostgreSQL: v14.0 or higher (or Neon serverless database)
• Operating System: Any OS that supports Node.js (Linux recommended for production)
• Memory: 1GB RAM minimum (2GB+ recommended)
• Storage: 1GB for application, database size depends on usage

Recommended Production Setup

• Node.js: Latest LTS version
• PostgreSQL: Latest stable version
• Operating System: Linux (Ubuntu 22.04 LTS or similar)
• Memory: 4GB RAM
• Storage: 10GB SSD
• Web Server: Nginx as a reverse proxy
• SSL Certificate: Let's Encrypt or similar

Installation

Option 1: Docker Deployment (Recommended)

1. Clone the repository:

   git clone https://github.com/yourusername/dynamodns.git
   cd dynamodns
   

2. Configure environment variables: Create a .env file based on the .env.example template:

   cp .env.example .env
   nano .env  # Edit with your configuration
   

3. Build and start the containers:

   docker-compose up -d
   

4. Run database migrations:

   docker-compose exec app npm run db:push
   

5. Create initial admin user (if not using the automated setup):

   docker-compose exec app npm run create-admin
   

Option 2: Manual Deployment

1. Clone the repository:

   git clone https://github.com/yourusername/dynamodns.git
   cd dynamodns
   

2. Install dependencies:

   npm install
   

3. Configure environment variables: Create a .env file with your configuration:

   # Database configuration
   DATABASE_URL=postgresql://user:password@localhost:5432/dynamodns
   
   # Server configuration
   PORT=5000
   NODE_ENV=production
   SESSION_SECRET=your_secure_session_secret
   
   # Authentication configuration
   ENABLE_REGISTRATION=false
   
   # Optional: LDAP configuration
   LDAP_ENABLED=false
   LDAP_URL=ldap://ldap.example.com
   LDAP_BIND_DN=cn=admin,dc=example,dc=com
   LDAP_BIND_PASSWORD=password
   LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
   LDAP_SEARCH_FILTER=(uid={{username}})
   
   # Optional: OpenID Connect configuration
   OIDC_ENABLED=false
   OIDC_ISSUER=https://auth.example.com
   OIDC_CLIENT_ID=your_client_id
   OIDC_CLIENT_SECRET=your_client_secret
   OIDC_CALLBACK_URL=https://dynamodns.example.com/api/auth/oidc/callback
   

4. Run database migrations:

   npm run db:push
   

5. Build the application:

   npm run build
   

6. Start the application:

   npm start
   

Configuration Options

Database Configuration

• DATABASE_URL: Connection string for PostgreSQL

Server Configuration

• PORT: The port on which the server will listen (default: 5000)
• NODE_ENV: Environment (development/production)
• HOST: Host to bind to (default: 0.0.0.0)
• SESSION_SECRET: Secret for session encryption (generate a secure random string)

Authentication Configuration

• ENABLE_REGISTRATION: Allow new user registration (true/false)
• DEFAULT_ADMIN_USERNAME: Username for the default admin (default: admin)
• DEFAULT_ADMIN_PASSWORD: Password for the default admin (set this for initial setup)
• DEFAULT_ADMIN_EMAIL: Email for the default admin (default: admin@example.com)

LDAP Configuration (Optional)

• LDAP_ENABLED: Enable LDAP authentication (true/false)
• LDAP_URL: LDAP server URL
• LDAP_BIND_DN: DN for binding to LDAP
• LDAP_BIND_PASSWORD: Password for binding to LDAP
• LDAP_SEARCH_BASE: Base DN for user search
• LDAP_SEARCH_FILTER: Filter for finding users (use {{username}} as placeholder)
• LDAP_USER_ATTR_USERNAME: LDAP attribute for username (default: uid)
• LDAP_USER_ATTR_EMAIL: LDAP attribute for email (default: mail)
• LDAP_USER_ATTR_DISPLAY_NAME: LDAP attribute for display name (default: cn)

OpenID Connect Configuration (Optional)

• OIDC_ENABLED: Enable OIDC authentication (true/false)
• OIDC_ISSUER: OIDC issuer URL
• OIDC_CLIENT_ID: Client ID for OIDC
• OIDC_CLIENT_SECRET: Client secret for OIDC
• OIDC_CALLBACK_URL: Callback URL for OIDC authentication
• OIDC_SCOPE: Scopes to request (default: "openid profile email")

DNS Provider Configuration

DynamoDNS supports multiple DNS providers. Each requires specific configuration:

Cloudflare

Required credentials:

• API Token or API Key + Email
• Zone IDs (optional, can be fetched automatically)

AWS Route53

Required credentials:

• Access Key ID
• Secret Access Key
• Region

GoDaddy

Required credentials:

• API Key
• API Secret

Generic Provider

For custom or unsupported providers:

• API URL
• Authentication method
• Request format

Setting Up Reverse Proxy

For production deployments, it's recommended to use a reverse proxy like Nginx or Apache.

Nginx Configuration Example

server {
    listen 80;
    server_name dynamodns.example.com;
    
    # Redirect to HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name dynamodns.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
    
    # Proxy to Node.js application
    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Database Backup and Maintenance

Automated Backups

For PostgreSQL:

# Add to crontab for daily backups
0 2 * * * pg_dump -U username -d dynamodns > /path/to/backup/dynamodns_$(date +\%Y\%m\%d).sql

For Neon PostgreSQL:

• Enable automated backups through the Neon dashboard
• Set an appropriate backup schedule and retention policy

Database Maintenance

Regular maintenance tasks:

# Vacuum the database to optimize performance
psql -U username -d dynamodns -c "VACUUM ANALYZE;"

# Check for slow queries
psql -U username -d dynamodns -c "SELECT * FROM pg_stat_activity WHERE state = 'active';"

System Monitoring

Health Check Endpoint

The application provides a health check endpoint at /api/health that returns:

• Application status
• Database connectivity
• DNS provider connectivity

Recommended Monitoring Tools

• Uptime Monitoring: Pingdom, UptimeRobot, or similar
• Application Monitoring: New Relic, Datadog, or similar
• Log Management: ELK Stack, Graylog, or similar

Security Considerations

Securing Your Deployment

1. Use HTTPS: Always use SSL/TLS in production
2. Firewall Configuration: Restrict access to the server
3. Regular Updates: Keep all dependencies up to date
4. Secure Credentials: Use environment variables, not hardcoded values
5. Rate Limiting: Configure rate limiting to prevent abuse

Data Protection

1. Encryption: Sensitive data is encrypted in the database
2. Backups: Regular encrypted backups
3. Access Control: Implement least privilege principle
4. Audit Logs: Monitor and review access logs

Upgrading

Standard Upgrade Process

1. Backup your data:

   pg_dump -U username -d dynamodns > /path/to/backup/dynamodns_before_upgrade.sql
   

2. Pull the latest changes:

   git pull origin main
   

3. Install dependencies:

   npm install
   

4. Run database migrations:

   npm run db:push
   

5. Rebuild the application:

   npm run build
   

6. Restart the service:

   # If using systemd
   sudo systemctl restart dynamodns
   
   # If using PM2
   pm2 restart dynamodns
   

Docker Upgrade Process

1. Pull the latest image:

   docker-compose pull
   

2. Restart the containers:

   docker-compose down
   docker-compose up -d
   

3. Run migrations:

   docker-compose exec app npm run db:push
   

Troubleshooting

Common Issues

1. Database Connection Errors:

   • Check DATABASE_URL environment variable
   • Verify network connectivity and firewall rules
   • Ensure PostgreSQL is running

2. Authentication Issues:

   • Verify SESSION_SECRET is set
   • Check LDAP/OIDC configuration if using external authentication

3. DNS Provider Integration Errors:

   • Verify API credentials for the DNS provider
   • Check for rate limiting or IP restrictions

Logs

Access logs for troubleshooting:

# Application logs
tail -f logs/app.log

# In Docker
docker-compose logs -f app

Getting Support

If you encounter issues not covered in this documentation:

1. Check the GitHub repository issues
2. Create a new issue with detailed information about your problem
3. Contact commercial support if you have a support agreement