Skip to content
Evolving EdgeEvolving Edge Docs

Edge Node Operator Guide

This guide will walk you through everything you need to get your edge node up and running - from installation to day-to-day management. By running a node, you’re contributing compute, bandwidth, and cache capacity to the Evolving Edge computing cloud and earning income for every workload you serve.

Before You Begin

Section titled “Before You Begin”

Residency Requirement

Section titled “Residency Requirement”

Node operators must currently reside in the United States to participate in the Evolving Edge computing cloud.

System Requirements

Section titled “System Requirements”

Make sure your device meets the following minimum specs before getting started:

Hardware

Component Minimum
CPU Dual-core
RAM 4 GB
Storage 10 GB available

Edge AI Inference hardware requirements are coming soon.

Supported Operating Systems

  • macOS 12 Monterey or later
  • Windows 10 or later
  • Linux Kernel 3.2 or later

Create an Account First

Section titled “Create an Account First”

You’ll need an Evolving Edge account to authorize your node. For the smoothest experience, create your account before starting the installation. See the account setup page for details.

Installation

Section titled “Installation”

Choose the installation method that works best for you.

Option 1 - Command Line (Recommended)

Section titled “Option 1 - Command Line (Recommended)”

This is the fastest way to get up and running. If you’d like to review the install script before running it, you can inspect it here:

https://cp.3dge.app/install.sh

Linux / MacOS

Terminal window
curl -fsSL https://cp.3dge.app/install.sh | sh

Windows (PowerShell)

Terminal window
irm https://cp.3dge.app/install.ps1 | iex

Non-Interactive Install (for automated setups)

Terminal window
curl -fsSL https://cp.3dge.app/install.sh | sh -s -- -y

What Happens During Installation

Section titled “What Happens During Installation”

The installer detects your operating system and architecture automatically, then walks you through three steps:

Step 1 - Download the edge node binary

EE-CDN Edge Node Installer
══════════════════════════════════════════════════════════════
  OS:            Linux
  Architecture:  amd64
  Install to:    ~/.ee-cdn/bin
  Control plane: Connected
  Mode:          Tokenless (device auth)


Step 1/3 — Download edge-node binary from Control Plane [Y/n]
Downloading from Control Plane...
  ✓ Checksum verified
  ✓ Binary installed to ~/.ee-cdn/bin/edge-node
  ✓ Version: 0.0.10

Step 2 - Authenticate your device

You’ll be prompted to visit the portal to verify your node:

Step 2/3 — Authenticate via device flow


=== Edge Node Authentication ===
Code: XXXX-XXXX
URL:  https://cp.3dge.app/device?user_code=XXXX-XXXX
Waiting for authorization...

Visit the URL shown, log in (or create an account if you haven’t yet), and authorize the device. Then return to your terminal.

Authorize Edge Node

Authorize Edge Node

You’ll see confirmation of a successful enrollment:

[Auth] Node enrolled: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
[Auth] Control plane:  ✓
[Auth] Config saved to ~/.ee-cdn/config.enc

Step 3 - Choose your cache size and install as a service

You’ll be asked how much disk space to allocate for caching:

How much disk space should this node use for caching?
  1) 1 GB
  2) 5 GB
  3) 10 GB (default)
  4) 25 GB
  5) 50 GB
Choose [1-5]: 3

Then you’ll be prompted to install as a system service. We strongly recommend saying yes - this keeps your node running in the background and ensures it restarts automatically when your device reboots.

Good to know: Uptime contributes to your payout calculation, so keeping the service running matters.

Step 3/3 — Install as system service (auto-start on boot)? [Y/n]

Once complete, you’ll see a status summary confirming everything is healthy:

Edge Node Status
  Node ID:    XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  Status:     healthy
  Region:     auto
  Port:       8080


Cache
  Size:       0 B / 10.0 GB (0%)
  Workloads:  0


Traffic
  Requests:   0
  Bytes:      0 B
  Peer Hits:  0


══════════════════════════════════════════════════════════════
  EE-CDN Edge Node setup complete!
══════════════════════════════════════════════════════════════

That’s it - your node is live!

Option 2 - Docker

Section titled “Option 2 - Docker”
Section titled “Docker Compose (Recommended)”

Download, install, and launch an edge node with one command:

curl -fsSL https://cp.3dge.app/docker-compose.yml -o docker-compose.yml && docker compose up -d

Or download the docker-compose.yml file and run:

Terminal window
docker-compose up -d

Docker Command

Section titled “Docker Command”

The Docker image is available here:

https://hub.docker.com/r/eecdn/ee-cdn-edge

Run the following command:

First create a machine ID file. Keep this file — it is what lets the container hold one node identity across recreations:

Terminal window
uuidgen | tr -d '-' > ~/edge-node-machine-id

On Windows, in PowerShell:

Terminal window
[guid]::NewGuid().ToString('N') | Out-File -Encoding ascii $HOME\edge-node-machine-id

Then create the volume and start the node:

Terminal window
docker volume create edge-data


docker run -d \
  --name edge-node \
  --hostname edge-node \
  --restart unless-stopped \
  -p 8080:8080 \
  -v edge-data:/data \
  -v ~/edge-node-machine-id:/etc/machine-id:ro \
  -e PORT=8080 \
  -e HOST=0.0.0.0 \
  -e HEARTBEAT_SECONDS=30 \
  -e CONTROL_PLANE_URL=https://cp.3dge.app \
  docker.io/eecdn/ee-cdn-edge:latest

The fixed hostname and the machine ID file are what keep this container’s node identity stable when it is recreated. Without them the node enrolls again as a new node, with no Active Node Hours, every time the container is replaced.

Create the machine ID file before running the command. If the path does not exist, Docker creates a directory there instead of mounting the file, and the node behaves as though no machine ID were set at all. See Node Identity.

Portainer

Section titled “Portainer”

You can deploy this as a Portainer Stack by pasting the Compose YAML into Portainer’s Web editor. The stack creates a persistent named Docker volume for node data and publishes the edge service on port 8080. docs.portainer

Before you begin

Make sure:

  • Portainer is connected to the Docker host where you want the edge node to run.
  • Port 8080 is available on that host. If it is already used, change the left side of the mapping—for example, 8081:8080.
  • The host has outbound HTTPS access to https://cp.3dge.app.
  • You have an edge-node identity/API credentials available if the service requires registration.

Create the stack

  1. Sign in to Portainer and select the target Docker environment.

  2. In the left navigation, open Stacks.

  3. Click Add stack.

  4. Enter a descriptive stack name, such as:

    evolving-edge-node

  5. Choose Web editor.

  6. Paste the Compose configuration found here: https://cp.3dge.app/docker-compose.yml

  7. Click Deploy the stack.

Portainer supports defining a stack directly in the Web editor using Docker Compose syntax; it also supports upload and Git-based deployment methods. docs.portainer

Confirm it started

  1. Return to Stacks and open 3dge-edge-node.
  2. Confirm the edge-node container is shown as running.
  3. Open the container, then select Logs.
  4. Check for successful startup, control-plane connection, and any registration/login prompts.

For a quick host-level test, browse to:

http://DOCKER_HOST_IP:8080

Whether this returns a useful page depends on the image’s API/health-endpoint design; a successful container state and logs are the primary checks.

Register the node

After deploying the stack, retrieve the activation information from the container logs:

  1. In Portainer, open Stacks from the left sidebar.
  2. Select the 3dge-edge-node stack.
  3. Open the edge-node container.
  4. Select Logs.
  5. Look for log entries containing the Activation ID and Activation URL.
  6. Open the activation URL in a browser and complete the registration flow, using the Activation ID if prompted.

If the activation details do not appear immediately, wait 15–30 seconds and refresh the log view. You can also use the Follow logs option to stream new output as the node starts.

Do not delete the edge-data volume after activation: it stores the container’s persistent node data, including registration-related state.

Persistence and updates

  • The edge-data named volume persists data even if the container is recreated.
  • restart: unless-stopped brings the container back after Docker or host restarts, unless you explicitly stop it.
  • To update the image later, redeploy the stack after pulling the current latest image, or use Portainer’s image/container management workflow. The persistent edge-data volume should remain intact—do not remove it unless you deliberately want to reset the node’s local state.

Dockge

Section titled “Dockge”

You can deploy the edge node in Dockge as a Compose stack, then retrieve its Activation ID and Activation URL from the service logs. Dockge is specifically a Compose-focused, stack-oriented Docker manager, so this workflow maps directly to the supplied YAML. hub.docker

Before you begin

Confirm that:

  • Dockge is connected to the Docker host where the edge node should run.
  • Port 8080 is available on that host. If it is occupied, change the mapping to something such as "8081:8080".
  • The Docker host can make outbound HTTPS connections to https://cp.3dge.app.
  • You will keep the edge-data named volume. It persists /data across container recreation and updates.

Create the stack

  1. Open the Dockge web UI.

  2. Select Compose or Stacks in the sidebar, depending on your Dockge version.

  3. Click New Compose.

  4. Name the stack:

    3dge-edge-node

  5. In the Compose editor, paste the contents of the docker compose file found here:

`https://cp.3dge.app/docker-compose.yml`
  1. Click Deploy or Up.

Dockge stores and manages Compose stacks as Compose YAML files, commonly beneath its configured stacks directory (by default /opt/stacks), and invokes Docker Compose to manage the stack. hub.docker

Get activation details

After deployment:

  1. Open the 3dge-edge-node stack in Dockge.
  2. Locate the edge-node service/container.
  3. Open Logs.
  4. Look for the Activation ID and Activation URL in the startup output.
  5. Open the Activation URL in a browser.
  6. Complete activation, entering the Activation ID if the registration page requests it.

If the activation entry is not present yet, wait 15–30 seconds, refresh the log view, or enable live log streaming if your Dockge version provides it.

Verify and manage

  • Confirm the edge-node service shows as running after activation.
  • Use the stack’s Logs view for connectivity or registration troubleshooting.
  • Use Restart to restart the service after a configuration change.
  • Use Update or edit the Compose YAML and redeploy to apply changes.
  • Do not remove the edge-data Docker volume unless you intentionally want to reset the node’s local state.

The restart: unless-stopped setting tells Docker to restart the container after Docker or host restarts unless you have explicitly stopped it.

Home Assistant App (Coming Soon)

Section titled “Home Assistant App (Coming Soon)”

You’ll be able to use your existing Home Assistant instance to participate in the Edge Computing Cloud.

NAS Devices

Section titled “NAS Devices”

Running a node on a NAS is a great way to contribute to the network without tying up a primary machine. Below are instructions for popular NAS platforms. Note that we’re unable to provide direct technical support for third-party environments - but our Discord community and the platform-specific communities are great places to get help.

For video walkthroughs from popular creators, check out the Resources page.

TrueNAS Scale

Section titled “TrueNAS Scale”

Retrieve the contents of the Docker Compose file here: https://cp.3dge.app/docker-compose.yml

Before you begin

  • Confirm the TrueNAS host has outbound HTTPS connectivity to https://cp.3dge.app.
  • Ensure TCP port 8080 is not already in use by another app.
  • Decide which pool will hold persistent edge-node state. This guide uses tank, but replace it with your pool name.

Create persistent storage

  1. Go to Datasets.

  2. Select your pool, such as tank.

  3. Click Add Dataset.

  4. Name it:

    appdata/ee-cdn

    This produces the host path:

    /mnt/tank/appdata/ee-cdn

  5. Save the dataset.

Use this dataset only for the edge node’s persistent /data directory. Do not mount it read-only: the application must be able to write node state and activation information.

Deploy the custom app

  1. Open Apps → Discover Apps.

  2. Click the three-dot menu next to Custom App, then select Install via YAML.

  3. Set the application name to a lowercase name such as:

    ee-cdn-edge

  4. Paste the contents of the Docker Compose file into Custom Config, replacing tank with your actual ZFS pool name, found here:

https://cp.3dge.app/docker-compose.yml`
  1. Click Save to pull the image and deploy the app.

The key change from the upstream Compose file is:

- /mnt/tank/appdata/ee-cdn:/data

This bind-mounts the ZFS dataset into the container at /data; it replaces the original edge-data:/data named-volume declaration. TrueNAS documents host-path mounts as the recommended on-disk persistence approach for production deployments. apps.truenas

Activate the edge node

  1. Go to Apps → Installed.
  2. Select ee-cdn-edge.
  3. Open its Logs.
  4. Wait for the container startup output, then locate the Activation ID and Activation URL.
  5. Open the Activation URL in a browser.
  6. Complete the activation flow, entering the Activation ID if requested.

If those lines do not appear immediately, wait 15–30 seconds and refresh or follow the app logs.

Verify and maintain

  • Confirm the app status is Running after activation.

  • Use the app’s Logs screen to troubleshoot connectivity or registration issues.

  • To update the configuration, edit/redeploy the YAML app rather than manually modifying internal TrueNAS app-storage paths.

  • Keep /mnt/tank/appdata/ee-cdn intact during updates and reinstallations; deleting it intentionally resets the node’s persisted state.

  • If port 8080 is occupied, change only the host side of the mapping, for example:

    ports:
      - "8081:8080"

The TrueNAS YAML editor accepts Docker Compose configuration with a top-level services: key and deploys it when you click Save. apps.truenas

Unraid

Section titled “Unraid”

Before you begin

  • Confirm port 8080 is not already assigned to another Unraid container.

  • Ensure the Unraid host can make outbound HTTPS connections to https://cp.3dge.app.

  • Use the canonical Compose file as the configuration source: https://cp.3dge.app/docker-compose.yml.

  • If you plan to replace the Compose named volume with an Unraid host path, create the directory first:

    text

    /mnt/user/appdata/ee-cdn

Install and deploy

  1. In Unraid, open the Apps tab.

  2. Search for and install Compose Manager / Docker Compose Manager.

  3. Open Docker → Compose. Depending on the plugin/version, this may appear as Compose in the top navigation.

  4. Click Add Stack.

  5. Name the stack:

    text

    ee-cdn-edge

  6. Retrieve the canonical Compose file from cp.3dge.app/docker-compose.yml, then paste its contents into the stack editor.

  7. Click Compose Up to pull docker.io/eecdn/ee-cdn-edge:latest and start the stack.

  8. Confirm the stack and its edge-node container show as running.

Compose Manager’s documented stack flow is Docker → Compose → Add Stack, followed by entering Compose YAML and selecting Compose Up.github

Optional Unraid storage path

The canonical Compose file uses the Docker named volume edge-data. That is valid on Unraid and is the simplest option.

If you prefer to keep edge-node state under Unraid’s usual appdata path, change only the volume mapping in the pasted Compose YAML:

volumes:
  - /mnt/user/appdata/ee-cdn:/data

Remove the top-level volumes: declaration for edge-data if it is no longer referenced:

volumes:
  edge-data:

Do not use both mappings for /data. Use either the original named volume or the Unraid host-path mapping.

Activate and verify

  1. Go to Docker or Docker → Compose and open the ee-cdn-edge stack/container.
  2. Select Logs.
  3. Locate the Activation ID and Activation URL in the startup logs.
  4. Open the Activation URL in a browser and complete the activation flow.
  5. Enter the Activation ID if the activation page asks for it.

If the activation values do not appear immediately, wait 15–30 seconds, refresh the logs, or use live log streaming if available.

Manual Docker template

Use this only if you do not want to install a Compose-management plugin.

  1. Open Docker → Add Container.

  2. Set the container name to:

    text

    ee-cdn-edge

  3. Set Repository to:

    text

    docker.io/eecdn/ee-cdn-edge:latest

  4. Set the network type to Bridge.

  5. Add a port mapping:

    Field Value
    Name Edge Node HTTP
    Container Port 8080
    Host Port 8080
    Protocol TCP

  6. Add one persistent path mapping:

    Field Value
    Name Edge node data
    Container Path /data
    Host Path /mnt/user/appdata/ee-cdn
    Access mode Read/Write

  7. Add these environment variables:

    Key Value
    Key Value
    PORT 8080
    HOST 0.0.0.0
    HEARTBEAT_SECONDS 30
    CONTROL_PLANE_URL https://cp.3dge.app

  8. Click Apply.

  9. Open the new container’s Logs and complete activation using the displayed Activation URL and Activation ID.

Unraid maps host ports to container ports in Bridge mode, and its Docker configuration supports runtime environment variables and host-path storage mappings. Avoid changing the container port unless the application itself supports a different listening port; change only the host port to resolve a conflict.unraid

Operational note

Use Compose Down or stop the container before maintenance. Keep the named volume or /mnt/user/appdata/ee-cdn directory intact during updates: it contains the node’s persistent /data state.

Synology

Section titled “Synology”

Use Container Manager Projects as the primary Synology method. It directly supports Docker Compose files, preserves the service definition as a project, and is easier to maintain than manually reproducing the configuration in the container wizard. kb.synology

Before you begin

  • Install Container Manager from Package Center if it is not already installed.
  • Confirm that port 8080 is not already used by another NAS service or container.
  • Ensure the NAS has outbound HTTPS access to https://cp.3dge.app.
  • Retrieve the canonical Compose configuration from docker-compose.yml.
  • Identify your actual volume name. This guide uses volume1; use the path that matches your NAS, such as /volume2/docker/....

Projects method

Create persistent storage

  1. Open File Station.

  2. Open the docker shared folder—commonly located at:

    /volume1/docker

  3. Create a folder named:

    ee-cdn

  4. Create a data folder inside it:

    /volume1/docker/ee-cdn/data

The resulting host directory for persistent node data is:

/volume1/docker/ee-cdn/data

Create the directory before deployment. Synology’s Container Manager requires host paths to exist for bind-mounted storage.

Create the Compose project

  1. Open Container Manager.

  2. Select Project in the left navigation.

  3. Click Create.

  4. Enter these general settings:

    Field Value
    Project Name ee-cdn-edge
    Path /volume1/docker/ee-cdn
    Source Create docker-compose.yml

  5. Retrieve the canonical YAML from cp.3dge.app/docker-compose.yml and paste it into the editor.

  6. Replace the canonical named-volume mapping:

    volumes:
      - edge-data:/data

    with the Synology host-path mapping:

    volumes:
      - /volume1/docker/ee-cdn/data:/data

  7. Remove the now-unused top-level named-volume declaration:

    volumes:
      edge-data:

  8. Click Next, review the configuration, and select Done.

  9. Choose Start project after creation when prompted.

Container Manager’s Project workflow supports setting a project name and working directory, then either uploading a Compose file or creating one with its editor. kb.synology

Activate the node

  1. In Container Manager → Project, select ee-cdn-edge.
  2. Open the edge-node container/service.
  3. Select Log.
  4. Locate the Activation ID and Activation URL in the startup output.
  5. Open the Activation URL in a browser and complete the activation workflow.
  6. Enter the Activation ID if the registration page requests it.

If the details do not appear yet, wait 15–30 seconds and refresh the log view.

Manual container method

Use this only if you do not want to use a Compose Project.

  1. Open Container Manager → Registry.

  2. Search for:

    eecdn/ee-cdn-edge

  3. Download the latest image.

  4. Open Image, select eecdn/ee-cdn-edge:latest, then click Run or Launch.

  5. Set the container name to:

    ee-cdn-edge

  6. Open Advanced Settings and configure:

    Setting Value
    Auto-restart Enabled
    Local port 8080
    Container port 8080
    Protocol TCP
    Host path /volume1/docker/ee-cdn/data
    Mount path /data
    Mount mode Read/Write

  7. Add these environment variables:

    Variable Value
    PORT 8080
    HOST 0.0.0.0
    HEARTBEAT_SECONDS 30
    CONTROL_PLANE_URL https://cp.3dge.app

  8. Click Next → Done, then start the container.

  9. Open the container’s Log tab and use the displayed Activation URL and Activation ID to activate it.

Synology’s container wizard supports image selection, auto-restart, port mappings, volume mounts, and environment variables under advanced settings. kb.synology

Maintenance notes

  • Keep /volume1/docker/ee-cdn/data when updating, restarting, or recreating the project; it contains the edge node’s persistent /data state.

  • If host port 8080 conflicts with another service, change only the host side of the mapping—for example:

    ports:
      - "8081:8080"

  • When using Projects, make configuration changes by editing the project Compose YAML and redeploying the project rather than changing the generated container manually.

QNAP QTS / QuTS Hero

Section titled “QNAP QTS / QuTS Hero”

Use Container Station → Applications → Create as the primary method. QNAP’s Applications feature is designed to deploy one or more containers from Docker Compose YAML, and it includes YAML validation before deployment. qnap

Before you begin

  • Install Container Station from App Center if it is not already installed.
  • Confirm that TCP port 8080 is not in use by another Container Station application or QNAP service.
  • Confirm the NAS can make outbound HTTPS connections to https://cp.3dge.app.
  • Retrieve the canonical Compose file from docker-compose.yml.
  • Identify the correct QNAP shared-folder path. This guide uses /share/Container/ee-cdn; your NAS may expose a different shared-folder path.

Create persistent storage

  1. Open File Station.

  2. Create a folder for the node’s persistent application data, for example:

    /share/Container/ee-cdn

    Alternatively, create it inside an existing shared folder, such as:

    /share/<volume-or-share-name>/ee-cdn

  3. Ensure the folder is writable by Container Station.

A host-path bind mount is preferable here because the edge-node state is visible, can be included in NAS backups/snapshots, and remains available if the application is recreated. Container Station supports host-path bind mounts as well as Docker-managed volumes. qnap

Deploy as an application

  1. Open Container Station.

  2. Select Applications in the left navigation.

  3. Click Create.

  4. Enter an application name using lowercase letters, numbers, hyphens, or underscores:

    ee-cdn-edge

  5. Retrieve the canonical YAML from cp.3dge.app/docker-compose.yml, then paste it into the Docker Compose YAML editor.

  6. In the pasted YAML, replace the original named-volume mapping:

    volumes:
      - edge-data:/data

    with your QNAP persistent host-path mapping:

    volumes:
      - /share/Container/ee-cdn:/data

  7. Remove the unused top-level named-volume declaration:

    volumes:
      edge-data:

  8. Click Validate YAML and correct any reported formatting errors.

  9. Click Create to pull the image and deploy the application.

The important resulting configuration is that the container’s /data directory maps to the NAS folder:

- /share/Container/ee-cdn:/data

QNAP documents the Applications workflow as Applications → Create → application name → Docker Compose YAML → Create, with optional YAML validation. qnap

Activate the edge node

  1. In Container Station, open Applications.
  2. Select ee-cdn-edge.
  3. Open the edge-node container/service details.
  4. View Logs.
  5. Find the Activation ID and Activation URL in the startup output.
  6. Open the Activation URL in a browser and complete the activation flow.
  7. Enter the Activation ID if the registration flow requests it.

Wait 15–30 seconds and refresh the logs if the activation information has not appeared yet.

Verify and maintain

  • Confirm the edge-node container is running.

  • Review Logs if startup, connectivity, or activation fails.

  • Preserve /share/Container/ee-cdn when updating or recreating the application; it holds persistent edge-node state.

  • Make future configuration changes by editing the application’s Compose YAML and applying the updated configuration.

  • If port 8080 conflicts with another application, change only the host port:

    ports:
      - "8081:8080"

Container Station supports Compose applications directly; it also supports normal individual-container configuration with bind mounts, environment variables, and port mappings if a manual fallback is needed. qnap

Umbrel

Section titled “Umbrel”

Umbrel

The recommended Umbrel installation method is to add the Evolving Edge Community App Store and install the edge node from the catalog. Umbrel Community App Stores distribute packaged apps—including their Compose configuration—through a Git repository, so users do not need to manually copy the canonical Compose file. github

Install from the Community App Store

  1. Open the Umbrel dashboard.

  2. Go to App Store.

  3. Open Community App Stores. Depending on your umbrelOS version, this may appear under Settings → App Store → Add Community Store.

  4. Click Add Community App Store.

  5. Paste this repository URL:

    https://github.com/evolving-edge/evolving-edge-umbrel-community-app-store

  6. Click Add.

  7. Return to the App Store and search for Evolving Edge, 3DGE, or the edge-node app name.

  8. Open the app listing and click Install.

  9. Wait for Umbrel to download the image and start the app.

Community App Stores allow developers to distribute Dockerized Umbrel applications outside the official App Store, and Umbrel supports adding a store by supplying its Git repository URL. github

Activate the edge node

  1. From the Umbrel home screen, open the installed edge-node app.
  2. Open the app’s Logs or View logs option.
  3. Locate the Activation ID and Activation URL in the startup output.
  4. Open the Activation URL in a browser.
  5. Complete the activation workflow, entering the Activation ID if prompted.

If activation details are not visible immediately, wait 15–30 seconds and refresh the logs.

Persistent data

Umbrel’s app package manages its own Compose configuration and persistent app-data location. Do not delete the app’s data directory when updating, restarting, or reinstalling unless you intentionally want to reset the edge node’s persistent state and activation data.

Manual Compose reference

For users who need to inspect the canonical Docker Compose configuration, it is available at cp.3dge.app/docker-compose.yml. The Community App Store installation is preferred because it is packaged for Umbrel and removes the need to manually translate Docker volume paths or Compose settings.

UGREEN UGOS Pro

Section titled “UGREEN UGOS Pro”

Use Docker → Projects for the recommended installation path. A Compose project preserves the canonical configuration in one editable deployment and avoids manually re-creating the image, port, storage, restart policy, and environment variables. UGOS Pro supports Docker on compatible DXP-series systems, while some ARM-based UGOS models do not support Docker.

Before You Begin

  • Confirm your UGREEN NAS model and UGOS version support Docker.
  • Open App Center and install Docker or Container Manager if it is not already installed.
  • Verify that port 8080 is unused.
  • Ensure the NAS can reach https://cp.3dge.app over outbound HTTPS.
  • Retrieve the canonical Compose file from docker-compose.yml.

Create Persistent Storage

  1. In UGOS, create or identify a shared folder for Docker app data, such as:

    appdata

  2. Create an application-specific subfolder:

    ee-cdn

  3. Use the UGOS host path for that shared folder in the Compose configuration. On UGOS Pro, shared folders are generally available to Docker as /media/<share-name>, for example:

    /media/appdata/ee-cdn

  4. Ensure the Docker service can write to that folder.

For this deployment, persistent container data belongs at /data; map that container path to the NAS folder you created. Host-path storage keeps the node’s state outside the disposable container.

Deploy With Projects

  1. Open Docker from the UGOS application menu.

  2. Select Projects.

  3. Click Create.

  4. Name the project:

    ee-cdn-edge

  5. Choose a project directory, such as:

    /media/appdata/ee-cdn

  6. Retrieve the canonical Compose YAML from cp.3dge.app/docker-compose.yml, then paste it into the project editor.

  7. Replace the canonical named-volume mapping:

    volumes:
      - edge-data:/data

    with the UGOS bind mount:

    volumes:
      - /media/appdata/ee-cdn:/data

  8. Remove the now-unused top-level Docker named-volume section:

    volumes:
      edge-data:

  9. Click Deploy.

  10. Confirm that the edge-node container starts and shows a running status.

Docker Compose project definitions include the image, ports, persistent mounts, environment variables, and restart policy in a single reusable YAML file. ai.ugreen

Activate The Edge Node

  1. In Docker → Containers or the ee-cdn-edge project details, open the edge-node container.
  2. Select Logs.
  3. Find the Activation ID and Activation URL in the startup output.
  4. Open the Activation URL in a browser.
  5. Complete the activation flow, entering the Activation ID if requested.

If the activation information is not visible immediately, wait 15–30 seconds and refresh or follow the logs.

Single Container Method

Use this only if the Projects/Compose feature is unavailable.

  1. Open Docker → Container → Create.

  2. Set the image to:

    docker.io/eecdn/ee-cdn-edge:latest

  3. Name the container:

    ee-cdn-edge

  4. Enable automatic restart.

  5. Configure the port mapping:

    Host port Container port Protocol
    8080 8080 TCP

  6. Configure persistent storage:

    Host path Container path Access
    /media/appdata/ee-cdn /data Read/Write

  7. Add these environment variables:

    Variable Value
    PORT 8080
    HOST 0.0.0.0
    HEARTBEAT_SECONDS 30
    CONTROL_PLANE_URL https://cp.3dge.app

  8. Click Apply or Create to start the container.

  9. Open its logs and complete activation with the shown Activation URL and Activation ID.

Maintenance Notes

  • Preserve /media/appdata/ee-cdn during restarts, updates, and container recreation; it contains the persistent /data state.

  • If port 8080 is unavailable, change only the external/host port, for example:

    ports:
      - "8081:8080"

  • Make Compose configuration changes by editing and redeploying the Project, rather than changing the generated container manually.

ZimaOS / CasaOS

Section titled “ZimaOS / CasaOS”

Use Install a Custom App to deploy the edge node from its Docker Compose configuration. ZimaOS and CasaOS custom applications are Compose-based, allowing you to import a Docker Compose YAML file directly through the App Store interface.

Before You Begin

  • Confirm that port 8080 is not already assigned to another app.

  • Ensure the host can make outbound HTTPS connections to https://cp.3dge.app.

  • Retrieve the canonical Compose configuration from docker-compose.yml.

  • Create a persistent data directory for the edge node:

    /DATA/AppData/ee-cdn

    If your installation uses a different data disk or mount path, use the equivalent location on that disk.

Import The Custom App

  1. Open the App Store.

  2. Click Install a Custom App. In some ZimaOS versions, click the + button on the dashboard and select Install a customized app.

  3. Select Import.

  4. Open the Docker Compose tab.

  5. Retrieve the canonical YAML from cp.3dge.app/docker-compose.yml, then paste it into the editor.

  6. Replace the canonical named-volume mapping:

    volumes:
      - edge-data:/data

    with the ZimaOS/CasaOS host-path bind mount:

    volumes:
      - /DATA/AppData/ee-cdn:/data

  7. Remove the unused named-volume declaration at the end of the YAML:

    volumes:
      edge-data:

  8. Click Submit.

  9. Review the imported app settings.

  10. Set the app name to:

ee-cdn-edge
  1. Verify that the storage mapping shows /DATA/AppData/ee-cdn on the host and /data inside the container.
  2. Click Install.

ZimaOS documents this flow as Install a customized app → Import → Docker Compose → paste YAML → Submit. zimaspace

Activate The Edge Node

  1. Open the installed ee-cdn-edge app from the dashboard.
  2. Open the container’s Logs or View logs panel.
  3. Find the Activation ID and Activation URL in the startup output.
  4. Open the Activation URL in a browser.
  5. Complete the activation workflow, entering the Activation ID if requested.

If the information has not appeared yet, wait 15–30 seconds and refresh the log view.

Storage And Updates

  • Keep /DATA/AppData/ee-cdn when restarting, updating, or reinstalling the application. It holds the persistent edge-node /data state.

  • Use only the basic bind-mount syntax shown above—/host/path:/container/path. The ZimaOS web UI may not support Docker mount options such as :ro or :shared, though this edge-node mapping does not require them. community.zimaspace

  • If port 8080 is already in use, change only the host-side port mapping:

    ports:
      - "8081:8080"

  • For future configuration changes, re-import or edit the custom app’s Compose configuration rather than modifying the generated container directly.

OpenMediaVault (OMV)

Section titled “OpenMediaVault (OMV)”

Use the openmediavault-compose plugin to deploy the edge node. It provides Docker Compose management directly in the OMV web interface and is the recommended OMV workflow for Compose-based applications. wiki.omv-extras

Before You Begin

  • Confirm port 8080 is not already assigned to another service or container.
  • Ensure the OMV host can make outbound HTTPS connections to https://cp.3dge.app.
  • Retrieve the canonical Compose file from docker-compose.yml.
  • Plan to store Docker data on a data disk, SSD, or array—not the OMV operating-system disk. The Compose plugin can relocate Docker storage from the default /var/lib/docker path. wiki.omv-extras

Install OMV-Extras

  1. SSH into the OMV server as root, or run the command through OMV’s System → Scheduled Jobs / command-line access.

  2. Install OMV-Extras:

    Terminal window
    wget -O - https://github.com/OpenMediaVault-Plugin-Developers/packages/raw/master/install | bash

  3. Wait for the script to finish, then refresh the OMV web interface.

This is the installation command published by OMV-Extras for OMV. omv-extras

Enable Docker And Compose

  1. In the OMV web interface, go to System → OMV-Extras.

  2. Select Docker Repo.

  3. Click Save and apply pending configuration changes.

  4. Go to System → Plugins.

  5. Search for:

    openmediavault-compose

  6. Select the plugin version appropriate to your OMV release—such as openmediavault-compose 7.x on OMV 7—and click Install.

  7. Wait for installation to complete and apply any pending changes.

Enabling the Docker repository makes Docker and the Compose plugin available; installing openmediavault-compose also installs its required dependencies. wiki.omv-extras

Configure Compose Storage

Before creating the edge-node Compose file, configure where OMV stores Compose definitions and Docker data.

  1. Go to Storage → Shared Folders.

  2. Create a shared folder named:

    appdata

    Place it on your preferred data disk or SSD.

  3. Optionally create shared folders for:

    compose
    backup-compose
    docker

  4. Go to Services → Compose → Settings.

  5. Under Compose Files, select the compose shared folder. This is where OMV stores generated Compose YAML and related .env files.

  6. Under Docker, set Docker Storage to the absolute path of your docker shared folder rather than leaving it on the OS disk.

  7. Under Data, select the appdata shared folder, then click Save and apply changes.

The Compose plugin stores Compose files in a user-selected folder and offers settings for Docker storage, application data, and backups. wiki.omv-extras

Create And Start The Edge Node

  1. Go to Services → Compose → Files.

  2. Click Add.

  3. Set the name to:

    ee-cdn-edge

  4. Retrieve the canonical Compose YAML from cp.3dge.app/docker-compose.yml, then paste it into the File editor.

  5. Leave the original named-volume configuration intact:

    volumes:
      - edge-data:/data

    This is the simplest supported configuration. Docker will manage the persistent edge-data volume.

  6. Click Save, then apply pending configuration changes.

  7. Select the ee-cdn-edge Compose file and click Up.

  8. Confirm the edge-node service/container shows as running.

The OMV plugin’s Services → Compose → Files page is where you create, edit, start, stop, update, and otherwise manage Compose-defined containers. wiki.omv-extras

Activate The Edge Node

  1. Go to Services → Compose → Services.
  2. Select the edge-node service.
  3. Open Logs.
  4. Find the Activation ID and Activation URL in the startup output.
  5. Open the Activation URL in a browser and complete activation.
  6. Enter the Activation ID if the activation page prompts for it.

If the activation information is not visible immediately, wait 15–30 seconds, then refresh or follow the service logs.

Updates And Maintenance

  • Preserve the edge-data Docker volume during updates and restarts; it holds the persistent /data state.

  • To update the image, select the Compose file or service, use Pull, then redeploy with Up. The plugin supports pulling updated images directly from its Compose management pages. wiki.omv-extras

  • If port 8080 conflicts with another service, edit only the host-side port mapping:

    ports:
      - "8081:8080"

  • Manage configuration changes in Services → Compose → Files instead of manually changing Docker-generated container settings.

Configuration

Section titled “Configuration”

All configuration lives in ~/.ee-cdn/:

File Purpose
config.enc Encrypted enrollment credentials (node ID, API key)
settings.json Capacity, GPU, and remote config preferences
cache/workloads/ Cached .ee workload files
logs/ Edge node logs

Settings

Section titled “Settings”

You can adjust settings through the portal or the CLI:

Setting Default Description
capacity_bytes 10 GB Disk space allocated for content caching
gpu_enabled false Enable GPU compute (opt-in)
allow_remote_config true Allow the portal to push configuration changes
webrtc_enabled true Enable WebRTC for P2P content delivery

Environment Variables

Section titled “Environment Variables”

You can override any setting using environment variables:

Variable Default Description
PORT 8080 HTTP listen port
HOST 127.0.0.1 Listen address (0.0.0.0 for LAN access)
CAPACITY_BYTES 10737418240 Cache capacity in bytes
CONTROL_PLANE_URL (from enrollment) Control plane URL

Service Management

Section titled “Service Management”

macOS

Section titled “macOS”
Terminal window
# Start
launchctl start ee-cdn-edge-node


# Stop
~/.ee-cdn/bin/edge-node stop


# Reinstall service
~/.ee-cdn/bin/edge-node install


# Check status
curl http://localhost:8080/health

Linux (systemd)

Section titled “Linux (systemd)”
Terminal window
# Start
systemctl --user start ee-cdn-edge-node


# Stop
systemctl --user stop ee-cdn-edge-node


# Status
systemctl --user status ee-cdn-edge-node


# View live logs
journalctl --user -u ee-cdn-edge-node -f

Additional systemd commands:

Terminal window
# Enable start on boot
systemctl enable ee-cdn-edge-node


# Disable start on boot
systemctl disable ee-cdn-edge-node

Verifying Your Node

Section titled “Verifying Your Node”

Check Health

Section titled “Check Health”
Terminal window
curl http://localhost:8080/health
# Returns: {"nodeId":"...","status":"healthy"}

Check Version

Section titled “Check Version”
Terminal window
~/.ee-cdn/bin/edge-node version

View in the Portal

Section titled “View in the Portal”

Visit portal.3dge.app to see your node’s status, cached content, and serving statistics.

How Content Delivery Works

Section titled “How Content Delivery Works”

Here’s what’s happening under the hood once your node is running:

  1. Your node registers with the control plane and receives workload assignments
  2. Content is cached locally as .ee workload files - these are compressed and optionally encrypted bundles
  3. When a browser needs content, it discovers your node via the WebTorrent tracker
  4. The browser establishes a WebRTC connection to your node - this works even behind NAT, so no port forwarding needed
  5. Your node serves compressed content pieces directly to the browser
  6. The browser decompresses and renders the content - no gateway required
  7. You get paid for every byte delivered

Automatic Updates

Section titled “Automatic Updates”

Edge nodes update themselves automatically when a new version is available:

  1. The control plane reports the latest version in the heartbeat response
  2. Your node downloads the new binary from the release server
  3. The binary is atomically replaced
  4. The process exits and the service manager restarts with the new version

To check your current version at any time:

Terminal window
~/.ee-cdn/bin/edge-node version

Next Steps

Section titled “Next Steps”
  1. Explore your dashboard - portal.3dge.app
  2. Join the community - discord.gg/KUGFX9a4Xn
  3. Spread the word - Invite others to join: portal.3dge.app/referrals

Have questions? Hop into Discord or submit a support request.