​
Configuration

To run Edge Server, you need a configuration file in YAML format. This can be configured in two ways: Small Peers Only mode or Server Sync mode.

​
Small Peers Only

Small Peers Only mode is a connection configuration type that restricts the Edge Server to only synchronize with other small peers (SDK instances) in the mesh network over LAN, BLE, and other local transport protocols. The HTTP API is still accessible in this mode. See HTTP Server Configuration If you are using the Edge Server in a small peer only mode, you can use the following configuration: 
resources:
  my_ditto_db:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    subscriptions: 
      - "SELECT * FROM tasks"
    auth:
      small_peers_only:
        offline_license_token: "YOUR_TOKEN_HERE"

​
Cloud Sync

The Edge Server can authenticate with the cloud platform (either Ditto-operated Cloud or your own) using your own authentication webhook provider. You will need to provide the appropriate credentials in your configuration file.
FieldExampleDescription
db_ida673b537-c02d-48da...Also known as “AppID”
access_tokenf72cbeb1-3735-59ef...Your app’s unique access token
provider__playgroundProviderThe provider name. If using Online Playground mode, use __playgroundProvider as your provider.
auth_urlhttps://i38a.dittolive.appThe URL for the Ditto authentication service
Replace the values with your actual Ditto AppID and Token from the Ditto Portal. 
resources:
  my_ditto_db:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    subscriptions:
      -  "SELECT * FROM tasks"
    auth:
      server:
        access_token: "YOUR_TOKEN"
        auth_url: "https://YOUR-AUTH-URL"
        provider: "__playgroundProvider"

​
Authentication & Permissions

When using Small Peer Only mode or Playground mode, all reads and writes are permitted. If you need more granular control over permissions, you can use Ditto’s authentication webhook provider system, which is configurable in the Ditto Portal. Edge server is compatible with these webhook providers. You
can configure connections to your webhook provider by providing the applicable token and provider name in the edge server configuration file. To learn more about custom authentication, see the Authentication Guide.

​
Best Practices

  1. Use UUIDs for db_id: Always use valid UUIDv4 format for database IDs
  2. Descriptive device names: Choose meaningful names for easier debugging
  3. Limit subscriptions: Only sync data you need to minimize bandwidth and storage
  4. Secure credentials: Use environment variables or secrets management for tokens
  5. Plan persistence: Choose appropriate storage locations with sufficient space
  6. Test connectivity: Verify network paths before deploying to production

​
Troubleshooting

​
Database Won’t Start

Check:
  • db_id is valid UUIDv4 format
  • Authentication credentials are correct
  • Persistence directory has write permissions
  • No other process is using the same database files

​
Peers Not Syncing

Verify:
  • Both peers have the same db_id
  • Authentication modes are compatible
  • Network connectivity exists between peers
  • Firewall rules allow Ditto traffic

​
High Disk Usage

Review:
  • Subscription queries aren’t too broad
  • Log level isn’t set to verbose
  • Old log files are being rotated/cleaned