User Manual
Docker
Version 1.0.0
OrpheAgent Containerized Version
Installation Using the One-Click Script
Step 1. Download the latest release
- Download the file to your device: orphe-agent-1.0.0-container.tar.gz.
- Extract the download
.tar.gzfile:tar -zxvf orphe-agent-1.0.0-container.tar.gz
Step 2. Generate a Provision Key on the OrpheLink
- Log in to the OrpheLink dashboard and navigate to the Provision page.
- Generate and copy a new Provision Key for your device.
Step 3. Installation Using the One-Click Script
- curl installed. Usually available in the official repositories and can be installed:
sudo apt install curl - Run the script with the appropriate parameters:
sudo bash install.sh ARCH DOCKER_USERNAME DOCKER_PASSWORD PROVISION_KEY- Replace ARCH with your system's architecture type (e.g.,
amd64,arm64,armhf). - Replace DOCKER_USERNAME and DOCKER_PASSWORD with your Docker Hub credentials.
- Replace PROVISION_KEY with the provision key you generated from the OrpheLink Provision page.
- The script will automatically update the
PROVISION_KEYin yourdocker-compose.ymlfile.
- Replace ARCH with your system's architecture type (e.g.,
- The script will automatically:
- Install Docker and Docker Compose if they are not already installed.
- Log in to Docker Hub using the provided credentials.
- Set the
PROVISION_KEYin thedocker-compose.ymlfile. - Build the Docker image for the specified architecture.
- Start the container using Docker Compose.
Step 4. Discover and Provision the New Agent on the OrpheLink
- Go back to the OrpheLink Provision page and click re-discover. The new agent will appear in the device list.
- Select the OrpheAgent device, then click the provision button at the bottom to let the OrpheLink take over management.
- After provisioning succeeds, you can see the device on the OrpheLink's inventory page.
Rebuild the Docker Image and Restart Containers using the One-Click Script
To rebuild the Docker image and restart the containers, you can use the rebuild method in the install.sh script. Follow these steps:
- Run the
rebuildmethod with the desired architecture (e.g.,amd64,arm64, orarmhf):
Replacesudo bash install.sh rebuild ARCHARCHwith your system's architecture type. For example:sudo bash install.sh rebuild amd64 - The script will automatically:
- Build the Docker image for the specified architecture.
- Stop and remove existing containers.
- Prune unused Docker resources.
- Restart the containers with the updated configuration.
-
By default, three named volumes will be created:
orphe-agent-db: stores OrpheAgent database filesorphe-agent-logs: stores OrpheAgent log filesorphe-agent-config: stores OrpheAgent configuration files (such asorphe-agent.yaml)
Files Overview
Dockerfile: Defines the container build process.-
entrypoint.sh:Script to initialize the container and configure the agent. -
bin/: Contains precompiled binaries of the OrpheAgent for different architectures (amd64,arm64,armhf). -
docker-compose.yml: Configuration file for Docker Compose to manage the container.
Environment Variables
The following environment variables can be used to configure the OrpheAgent:
-
PROVISION_KEY: Set the provision key for the agent (default: empty). -
HOST_NAME: Set the host name for the agent (default:orphe-agent). -
MGMT_PORT_HTTP: Set the HTTP management port (default:0). -
MGMT_PORT_HTTPS: Set the HTTPS management port (default:0). -
CONTROLPLANE_TUN_PORT: Set the control plane tunnel port (default:0). -
DATAPLANE_TUN_PORT: Set the data plane tunnel port (default:0). -
DATAPLANE_SNAT_ENABLED: Enable experimental Data Plane SNAT support (trueto enable,falseto disable; default:false). When set totrue, the container will automatically start OrpheAgent with SNAT enabled (-sflag). Warning: This is experimental and may cause unexpected behavior.
Use 0 to let the system assign a random port.
Notes
- The container runs in privileged mode to allow access to networking features such as iptables and iproute2.
- The
--net=hostoption is used to share the host network with the container. - Logs are written to
/var/log/orphe-agent.loginside the container. - The
/etc/orphe-agent/directory contains configuration files for the OrpheAgent, includingorphe-agent.yaml. This directory can be mounted as a volume to persist configuration changes.
Known Limitations / Notes
- Supported on Linux systems only (amd64, arm64, armhf).
- Automatic OTA update is not supported yet (manual upgrade required).
- Currently tested only on native Ubuntu 18.04, 20.04, 22.04, and 24.04.
