Skip to main content
Edge Server is currently in preview. It is not recommended for production use.Edge server is under rapid development as a result:
  • APIs may change without notice.
  • Configuration format may change without notice.
  • Features, and behavior may change without notice.
  • This documentation may quickly grow stale or become inaccurate.
If you are experiencing issues, please reach out to your Ditto contact.
This guide covers essential security practices for deploying Edge Server in production environments. A secure deployment requires both transport-layer security (TLS/HTTPS) and application-layer security (authentication and authorization).

​
Security Overview

A production Edge Server deployment should implement multiple layers of security:
  1. Transport Security: TLS/HTTPS encryption for all network traffic
  2. Authentication: API key authentication for HTTP endpoints
  3. Authorization: Permission-based access control
  4. Network Security: Proper firewall rules and network isolation
  5. Monitoring: Audit logging and health checks

​
TLS/HTTPS Configuration

TLS encrypts network traffic between clients and your Edge Server, preventing man-in-the-middle attacks and eavesdropping. Always use TLS in production deployments.

​
Certificate Requirements

Edge Server requires:
  • A valid TLS certificate file in PEM format (typically .pem or .crt extension)
  • The corresponding private key file in PEM format (typically .pem or .key extension)
The certificate should:
  • Match your server’s domain name or IP address
  • Be signed by a trusted Certificate Authority (CA) for production
  • Have appropriate key strength (2048-bit RSA minimum, 256-bit ECDSA recommended)

​
Obtaining TLS Certificates

Let’s Encrypt provides free, automated TLS certificates trusted by all major browsers. Using Certbot: Follow the official Certbot documentation to install Certbot and generate certificates for your domain. Select your web server type and operating system for specific instructions. After generating certificates with Certbot, they will typically be located at:
  • Certificate: /etc/letsencrypt/live/your-domain.com/fullchain.pem
  • Private key: /etc/letsencrypt/live/your-domain.com/privkey.pem
Configure Edge Server to use the certificates: 
http_server:
  listen_addr: "0.0.0.0:443"
  tls_config:
    cert: "/etc/letsencrypt/live/your-domain.com/fullchain.pem"
    key: "/etc/letsencrypt/live/your-domain.com/privkey.pem"
  http_api: true
Let’s Encrypt certificates expire after 90 days. Follow the Certbot renewal documentation to set up automatic renewal. After renewal, restart Edge Server to load the new certificates.

​
Option 2: Commercial Certificate Authority

Purchase certificates from providers like DigiCert, GlobalSign, or Sectigo. Follow their documentation to generate a Certificate Signing Request (CSR) and obtain your certificate.

​
Option 3: Self-Signed Certificates (Development Only)

For development and testing environments, you can generate self-signed certificates using OpenSSL. See the OpenSSL documentation for instructions on generating self-signed certificates for your platform. Once you have generated your certificate and key files, configure Edge Server: 
http_server:
  listen_addr: "127.0.0.1:8443"
  tls_config:
    cert: "./cert.pem"
    key: "./key.pem"
  http_api: true
Self-signed certificates are NOT trusted by browsers or HTTP clients by default. Only use them for local development. Never use self-signed certificates in production.
Testing self-signed certificates: 
# Allow self-signed cert with curl
curl -k https://localhost:8443/health

# Or add certificate to curl
curl --cacert cert.pem https://localhost:8443/health

​
TLS Configuration Examples

​
Basic HTTPS Configuration

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-server-prod"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "0.0.0.0:443"
  tls_config:
    cert: "/etc/ssl/certs/edge-server.crt"
    key: "/etc/ssl/private/edge-server.key"
  http_api: true
  enable_healthcheck: true

auth:
  identities:
    api_client:
      credential:
        api_key: "BASE64_HASH_FROM_CLI"
      permissions: [full_permissions]
      id: "production-client"
  permission_sets:
    full_permissions:
      permissions: full

​
Certificate Path Options

Certificate paths can be specified as:
  • Absolute path: /etc/ssl/certs/cert.pem
  • Relative to config file: ./certs/cert.pem
  • Relative to config file: ../certificates/cert.pem
http_server:
  listen_addr: "0.0.0.0:8443"
  tls_config:
    # Relative to config file
    cert: "./ssl/cert.pem"
    key: "./ssl/key.pem"
  http_api: true

​
Troubleshooting TLS

Common Issues:
  1. “No such file or directory” error
    • Verify certificate and key file paths are correct
    • Check file permissions (Edge Server must be able to read them)
    • Use absolute paths if relative paths aren’t working
  2. “Invalid certificate” error
    • Ensure the certificate matches the private key
    • Verify the certificate is in PEM format
    • Check certificate hasn’t expired
  3. “Connection refused” with HTTPS
    • Verify the port is correct
    • Check firewall rules allow the HTTPS port
    • Ensure no other service is using the port
  4. Browser shows “Not Secure” warning
    • For self-signed certificates, this is expected
    • For production, verify certificate is signed by a trusted CA
    • Check certificate Common Name (CN) matches your domain
Verify certificate and key: Use OpenSSL to verify your certificate and key match, and to check certificate details. See the OpenSSL documentation for commands to verify certificates and check expiration dates.

​
Client Authentication

Once TLS is configured to encrypt the transport layer, configure client authentication to control who can access your HTTP API endpoints. See the Client Authentication guide for detailed instructions on:
  • Generating secure API keys
  • Configuring identities and permission sets
  • Authenticating HTTP requests
  • Rotating API keys
  • Managing multiple clients

​
Database Authentication

In addition to HTTP API authentication, Edge Server’s database requires authentication to sync with peers and the cloud. This controls how your Edge Server participates in the Ditto mesh network and what data it can access. See the Database Authentication guide for configuration details on:
  • Cloud sync mode (connects to Ditto Cloud with webhook provider)
  • Small peer only mode (air-gapped local mesh)
  • Securing database credentials
  • Authentication webhook configuration

​
Production Security Checklist

​
Required for Production

  • Enable TLS/HTTPS - Use valid certificates from Let’s Encrypt or commercial CA
  • Enable HTTP API authentication - Configure API keys and permission sets
  • Configure database authentication - Use custom webhook provider (not playground mode) for cloud sync
  • Use strong credentials - Generate API keys with the CLI, never manually
  • Secure credential storage - Use secrets manager or environment variables for all tokens
  • Configure firewall rules - Restrict access to necessary ports only
  • Set up monitoring - Use health check endpoint for uptime monitoring
  • Enable rate limiting - Configure throttling to prevent DoS attacks
  • Use separate API keys per client - One key per service for easier rotation
  • Implement key rotation - Regularly rotate API keys
  • Minimize permissions - Use principle of least privilege
  • Monitor logs - Review audit logs for suspicious activity
  • Keep software updated - Apply Edge Server updates promptly
  • Use network isolation - Deploy in private VPC/network when possible
  • Configure request limits - Set appropriate max_body_size_mb for endpoints

​
Complete Secure Configuration Example

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-server-prod"
  auth:
    server:
      access_token: "YOUR_CLOUD_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      provider: "__playgroundProvider"
  persistence_dir:
    path: "/var/lib/edge-server/data"

http_server:
  listen_addr: "0.0.0.0:443"
  tls_config:
    cert: "/etc/letsencrypt/live/your-domain.com/fullchain.pem"
    key: "/etc/letsencrypt/live/your-domain.com/privkey.pem"
  http_api:
    execute:
      enabled: true
      max_body_size_mb: 2
    attachments_upload:
      enabled: true
      max_body_size_mb: 50
    attachments_download: true
    presence: true
  enable_healthcheck: true
  throttling:
    strategies:
      - strategy: ip_address
        max_requests: 1000
        window_secs: 60
      - strategy: api_key
        max_requests: 100
        window_secs: 60
  request_timeout_ms: 30000
  max_connections: 10000

auth:
  identities:
    production_api:
      credential:
        api_key: "BASE64_HASH_FROM_CLI"
      permissions: [api_permissions]
      id: "prod-api-service"
    monitoring:
      credential:
        api_key: "DIFFERENT_BASE64_HASH"
      permissions: [monitoring_permissions]
      id: "monitoring-service"
  permission_sets:
    api_permissions:
      permissions: full
    monitoring_permissions:
      permissions: data

logging:
  ditto_sdk: warning
  edge_server:
    level: info
    console_logs: std_out
    audit_logs:
      path: "/var/log/edge-server/audit"
    rotating_logs:
      directory:
        path: "/var/log/edge-server/app"
      prefix: "edge-server.log"
      rotation:
        frequency: daily
      max_files: 30