# Edge Node Operator Guide

> Install an Evolving Edge edge node from the command line or with Docker, check the system requirements, and manage your node day to day.

Source: https://docs.evolvingedge.ai/installation/

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

>### Residency Requirement
>
>Node operators must currently reside in the **United States** to participate in the Evolving Edge computing cloud.

### 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

You'll need an Evolving Edge account to authorize your node. For the smoothest experience, [create your account](https://portal.3dge.app) before starting the installation. See the [account setup page](https://docs.evolvingedge.ai/account/) for details.

---

## Installation

Choose the installation method that works best for you.

### 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**

```bash
curl -fsSL https://cp.3dge.app/install.sh | sh
```

**Windows (PowerShell)**

```powershell
irm https://cp.3dge.app/install.ps1 | iex
```

**Non-Interactive Install** (for automated setups)

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

#### 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](https://docs.evolvingedge.ai/images/authorize_edge_node.png)

![Authorize Edge Node](https://docs.evolvingedge.ai/images/node_authorized.png)


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

#### 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`](https://cp.3dge.app/docker-compose.yml) file and run:

```bash
docker-compose up -d
```

#### 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:

```bash
uuidgen | tr -d '-' > ~/edge-node-machine-id
```

On Windows, in PowerShell:

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

Then create the volume and start the node:

```bash
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](https://docs.evolvingedge.ai/node-config/).

#### 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](https://docs.portainer.io/user/docker/stacks/add)

**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:

   ```text
   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](https://docs.portainer.io/user/docker/stacks/add)

**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:

```text
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

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](https://hub.docker.com/r/louislam/dockge)

**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:

   ```text
   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`
```

6. 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](https://hub.docker.com/r/louislam/dockge)

**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)

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

### 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](https://discord.gg/KUGFX9a4Xn) and the platform-specific communities are great places to get help.

For video walkthroughs from popular creators, check out the [Resources page](https://docs.evolvingedge.ai/resources/).

---

#### 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:

   ```text
   appdata/ee-cdn
   ```

   This produces the host path:

   ```text
   /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:

   ```text
   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`
```

5. Click **Save** to pull the image and deploy the app.

The key change from the upstream Compose file is:

```yaml
- /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](https://apps.truenas.com/managing-apps/installing-custom-apps)

**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:

  ```yaml
  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](https://apps.truenas.com/managing-apps/installing-custom-apps)

---

#### 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](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](https://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](https://github.com/mstrhakr/compose_plugin)

**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](https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/managing-and-customizing-containers/)

**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

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](https://kb.synology.com/en-global/DSM/help/ContainerManager/docker_project?version=7)

**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](https://cp.3dge.app/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:

   ```text
   /volume1/docker
   ```

3. Create a folder named:

   ```text
   ee-cdn
   ```

4. Create a `data` folder inside it:

   ```text
   /volume1/docker/ee-cdn/data
   ```

The resulting host directory for persistent node data is:

```text
/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](https://cp.3dge.app/docker-compose.yml) and paste it into the editor.
6. Replace the canonical named-volume mapping:

   ```yaml
   volumes:
     - edge-data:/data
   ```

   with the Synology host-path mapping:

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

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

   ```yaml
   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](https://kb.synology.com/en-global/DSM/help/ContainerManager/docker_project?version=7)

**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:

   ```text
   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:

   ```text
   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](https://kb.synology.com/en-global/DSM/help/ContainerManager/docker_container?version=7)

**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:

  ```yaml
  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

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](https://www.qnap.com/en/how-to/tutorial/article/how-to-use-container-station-3)

**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](https://cp.3dge.app/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:

   ```text
   /share/Container/ee-cdn
   ```

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

   ```text
   /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](https://www.qnap.com/en/how-to/tutorial/article/how-to-use-container-station-3)

**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:

   ```text
   ee-cdn-edge
   ```

5. Retrieve the canonical YAML from [cp.3dge.app/docker-compose.yml](https://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:

   ```yaml
   volumes:
     - edge-data:/data
   ```

   with your QNAP persistent host-path mapping:

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

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

   ```yaml
   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:

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

QNAP documents the Applications workflow as **Applications → Create → application name → Docker Compose YAML → Create**, with optional YAML validation. [qnap](https://www.qnap.com/en/how-to/tutorial/article/how-to-use-container-station-3)

**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:

  ```yaml
  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](https://www.qnap.com/en/how-to/tutorial/article/how-to-use-container-station-3)

---

#### 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](https://github.com/getumbrel/umbrel-community-app-store)

**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:

   ```text
   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](https://github.com/getumbrel/umbrel-community-app-store)

**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](https://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

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](https://cp.3dge.app/docker-compose.yml).

**Create Persistent Storage**

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

   ```text
   appdata
   ```

2. Create an application-specific subfolder:

   ```text
   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:

   ```text
   /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:

   ```text
   ee-cdn-edge
   ```

5. Choose a project directory, such as:

   ```text
   /media/appdata/ee-cdn
   ```

6. Retrieve the canonical Compose YAML from [cp.3dge.app/docker-compose.yml](https://cp.3dge.app/docker-compose.yml), then paste it into the project editor.
7. Replace the canonical named-volume mapping:

   ```yaml
   volumes:
     - edge-data:/data
   ```

   with the UGOS bind mount:

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

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

   ```yaml
   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](https://ai.ugreen.com/blogs/knowledge/docker-docker-compose-ugreen-nas)

**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:

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

3. Name the container:

   ```text
   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:

  ```yaml
  ports:
    - "8081:8080"
  ```

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

---

#### 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](https://cp.3dge.app/docker-compose.yml).
- Create a persistent data directory for the edge node:

  ```text
  /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](https://cp.3dge.app/docker-compose.yml), then paste it into the editor.
6. Replace the canonical named-volume mapping:

   ```yaml
   volumes:
     - edge-data:/data
   ```

   with the ZimaOS/CasaOS host-path bind mount:

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

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

   ```yaml
   volumes:
     edge-data:
   ```

8. Click **Submit**.
9. Review the imported app settings.
10. Set the app name to:

   ```text
   ee-cdn-edge
   ```

11. Verify that the storage mapping shows `/DATA/AppData/ee-cdn` on the host and `/data` inside the container.
12. Click **Install**.

ZimaOS documents this flow as **Install a customized app → Import → Docker Compose → paste YAML → Submit**. [zimaspace](https://www.zimaspace.com/docs/zimaos/paperless-ai-install)

**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](https://community.zimaspace.com/t/how-do-we-use-volume-options-when-installing-a-custom-app/7963)
- If port 8080 is already in use, change only the host-side port mapping:

  ```yaml
  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)

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](https://wiki.omv-extras.org/doku.php?id=omv7:omv7_plugins:docker_compose)

**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](https://cp.3dge.app/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](https://wiki.omv-extras.org/doku.php?id=omv7:omv7_plugins:docker_compose)

**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:

   ```bash
   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](https://omv-extras.org/)

**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:

   ```text
   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](https://wiki.omv-extras.org/doku.php?id=omv7:omv7_plugins:docker_compose)

**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:

   ```text
   appdata
   ```

   Place it on your preferred data disk or SSD.

3. Optionally create shared folders for:

   ```text
   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](https://wiki.omv-extras.org/doku.php?id=omv7:omv7_plugins:docker_compose)

**Create And Start The Edge Node**

1. Go to **Services → Compose → Files**.
2. Click **Add**.
3. Set the name to:

   ```text
   ee-cdn-edge
   ```

4. Retrieve the canonical Compose YAML from [cp.3dge.app/docker-compose.yml](https://cp.3dge.app/docker-compose.yml), then paste it into the **File** editor.
5. Leave the original named-volume configuration intact:

   ```yaml
   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](https://wiki.omv-extras.org/doku.php?id=omv7:omv7_plugins:docker_compose)

**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](https://wiki.omv-extras.org/doku.php?id=omv7:omv7_plugins:docker_compose)
- If port 8080 conflicts with another service, edit only the host-side port mapping:

  ```yaml
  ports:
    - "8081:8080"
  ```

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

---

## 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

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, which visitors' browsers use to fetch files from your node |

### 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

### macOS

```bash
# 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)

```bash
# 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:

```bash
# Enable start on boot
systemctl enable ee-cdn-edge-node

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

---

## Verifying Your Node

### Check Health

```bash
curl http://localhost:8080/health
# Returns: {"nodeId":"...","status":"healthy"}
```

### Check Version

```bash
~/.ee-cdn/bin/edge-node version
```

### View in the Portal

Visit [portal.3dge.app](https://portal.3dge.app) to see your node's status, cached content, and serving statistics.

---

## 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

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:

```bash
~/.ee-cdn/bin/edge-node version
```

---

## Next Steps

1. **Explore your dashboard** - [portal.3dge.app](https://portal.3dge.app)
2. **Join the community** - [discord.gg/KUGFX9a4Xn](https://discord.gg/KUGFX9a4Xn)
3. **Spread the word** - Invite others to join: [portal.3dge.app/referrals](https://portal.3dge.app/referrals)

Have questions? Hop into Discord or [submit a support request](https://docs.evolvingedge.ai/node-support/).
