Document project architecture, setup, usage, and API endpoints

Adds comprehensive documentation including architecture, API reference, deployment, development, and user guides with README.md. Replit-Commit-Author: Agent Replit-Commit-Session-Id: 9111ef36-26c8-4085-84ca-a35dc1fec1b5 Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/7083d608-d6d3-4a6a-9a27-6286c5109627/910f6160-6716-488e-83e6-61256595c269.jpg
2026-08-19 14:16:16 +00:00 · 2025-05-24 02:16:17 +00:00
parent 31f81a754a
commit ae19ec9c3d
6 changed files with 1955 additions and 0 deletions
@@ -0,0 +1,380 @@
+# 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**:
+   ```bash
+   git clone https://github.com/yourusername/dynamodns.git
+   cd dynamodns
+   ```
+
+2. **Configure environment variables**:
+   Create a `.env` file based on the `.env.example` template:
+   ```bash
+   cp .env.example .env
+   nano .env  # Edit with your configuration
+   ```
+
+3. **Build and start the containers**:
+   ```bash
+   docker-compose up -d
+   ```
+
+4. **Run database migrations**:
+   ```bash
+   docker-compose exec app npm run db:push
+   ```
+
+5. **Create initial admin user** (if not using the automated setup):
+   ```bash
+   docker-compose exec app npm run create-admin
+   ```
+
+### Option 2: Manual Deployment
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/yourusername/dynamodns.git
+   cd dynamodns
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   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**:
+   ```bash
+   npm run db:push
+   ```
+
+5. **Build the application**:
+   ```bash
+   npm run build
+   ```
+
+6. **Start the application**:
+   ```bash
+   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
+
+```nginx
+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:
+
+```bash
+# 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:
+
+```bash
+# 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**:
+   ```bash
+   pg_dump -U username -d dynamodns > /path/to/backup/dynamodns_before_upgrade.sql
+   ```
+
+2. **Pull the latest changes**:
+   ```bash
+   git pull origin main
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+4. **Run database migrations**:
+   ```bash
+   npm run db:push
+   ```
+
+5. **Rebuild the application**:
+   ```bash
+   npm run build
+   ```
+
+6. **Restart the service**:
+   ```bash
+   # If using systemd
+   sudo systemctl restart dynamodns
+   
+   # If using PM2
+   pm2 restart dynamodns
+   ```
+
+### Docker Upgrade Process
+
+1. **Pull the latest image**:
+   ```bash
+   docker-compose pull
+   ```
+
+2. **Restart the containers**:
+   ```bash
+   docker-compose down
+   docker-compose up -d
+   ```
+
+3. **Run migrations**:
+   ```bash
+   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:
+
+```bash
+# 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