ControlCom Edge Server

The ControlCom Edge Server is a containerized application that enables local processing and communication between your IoT devices and the ControlCom Connect platform. Deploy it using Docker to create a bridge between your local network and the cloud.

Quick Start

The fastest way to get started with the ControlCom Edge Server is using a simple Docker run command:

docker run -p 3041:3041 public.ecr.aws/i0f2i6k7/edge-server:latest

This command will:

  • Pull the latest Edge Server image from the public ECR repository
  • Start the container with port 3041 exposed
  • Make the web interface available at http://localhost:3041

Note that this basic setup does not persist data between container restarts. For production deployments, see the Docker Compose Setup section below.

Docker Compose Setup

For production deployments, we recommend using Docker Compose to manage the Edge Server. This approach provides better control over configuration and ensures data persistence.

Step 1: Create the Docker Compose File

Create a new file named docker-compose.yml in your project directory:

version: '3'
services:
  EdgeServer:
    image: 'public.ecr.aws/i0f2i6k7/edge-server:latest'
    network_mode: bridge
    ports:
      - '3041:3041'
    volumes:
      - 'data:/data'
volumes:
  data:
    driver: local

You can create this file using your favorite text editor or by running:

cat > docker-compose.yml <<EOF
version: '3'
services:
  EdgeServer:
    image: 'public.ecr.aws/i0f2i6k7/edge-server:latest'
    network_mode: bridge
    ports:
      - '3041:3041'
    volumes:
      - 'data:/data'
volumes:
  data:
    driver: local
EOF

Step 2: Start the Edge Server

From the directory containing your docker-compose.yml file, run:

docker-compose up -d

This command will:

  • Pull the Edge Server image if not already present
  • Create the data volume for persistence
  • Start the container in detached mode
  • Map port 3041 to your host machine

Step 3: Verify the Container is Running

Check that the Edge Server is running:

docker-compose ps

You should see the EdgeServer service listed as Up.

To view the logs:

docker-compose logs -f EdgeServer

Managing the Edge Server

Stop the Edge Server:

docker-compose down

Restart the Edge Server:

docker-compose restart

Update to the latest version:

docker-compose pull
docker-compose up -d

Configuration

The Edge Server supports optional environment variables for customization. Add these to your docker-compose.yml file under the environment section:

version: '3'
services:
  EdgeServer:
    image: 'public.ecr.aws/i0f2i6k7/edge-server:latest'
    network_mode: bridge
    ports:
      - '3041:3041'
    environment:
      - DEVICE_TIMEZONE=America/New_York
      - LOG_LEVEL=info
    volumes:
      - 'data:/data'
volumes:
  data:
    driver: local

Available Environment Variables

DEVICE_TIMEZONE

  • Sets the timezone for the Edge Server
  • Must be a valid timezone identifier (e.g., UTC, America/New_York, Europe/London, Asia/Tokyo)
  • Defaults to UTC if not specified

LOG_LEVEL

  • Controls the verbosity of logging output
  • Valid options: trace, debug, info, warn, error, fatal
  • Defaults to info if not specified
  • Use debug or trace for troubleshooting, warn or error for production

Example with custom configuration:

environment:
  - DEVICE_TIMEZONE=Europe/Berlin
  - LOG_LEVEL=debug

Data Persistence

The Edge Server stores important data including device onboarding information, configuration, and local cache. To ensure this data persists across container restarts and updates, mount a Docker volume to the /data directory inside the container.

Why Data Persistence Matters

Without a persistent volume:

  • Device onboarding will be lost when the container restarts
  • Configuration changes will not be saved
  • Local data cache will be cleared on every restart
  • You will need to re-onboard devices after updates

Configuring the Data Volume

The recommended docker-compose.yml configuration includes a named volume:

volumes:
  - 'data:/data'

This creates a Docker-managed volume named data that persists on your host system.

Alternative: Host Directory Binding

You can also mount a specific host directory instead of using a Docker volume:

volumes:
  - '/path/to/your/data:/data'

For example, to store data in your home directory:

volumes:
  - '~/controlcom-edge-data:/data'

Managing the Data Volume

View existing volumes:

docker volume ls

Inspect the data volume:

docker volume inspect <project-directory>_data

Backup the data volume:

docker run --rm -v <project-directory>_data:/data -v $(pwd):/backup alpine tar czf /backup/edge-server-backup.tar.gz -C /data .

Restore from backup:

docker run --rm -v <project-directory>_data:/data -v $(pwd):/backup alpine tar xzf /backup/edge-server-backup.tar.gz -C /data

Device Onboarding

Once the Edge Server is running, you need to onboard it to your ControlCom Connect organization. This process links the Edge Server to your account and allows it to communicate with the platform.

Onboarding Process

Follow these steps to onboard your Edge Server:

Step 1: Access the Web Interface

Open your web browser and navigate to:

http://localhost:3041

If you are accessing the Edge Server from a different machine on your network, replace localhost with the server's IP address.

Step 2: Login with ControlCom Connect Credentials

You will be presented with a login screen. Enter your ControlCom Connect credentials:

  • Email address
  • Password

These are the same credentials you use to access the ControlCom Connect web platform.

Step 3: Select Your Organization

After successful authentication, you will see a list of organizations associated with your account. Select the organization you want to onboard this Edge Server to.

Step 4: Complete Onboarding

Follow the on-screen prompts to complete the onboarding process. The Edge Server will:

  • Register itself with the selected organization
  • Download necessary configuration
  • Establish a secure connection to ControlCom Connect

Step 5: Verify Onboarding

Once onboarding is complete, you can verify the Edge Server appears in your ControlCom Connect dashboard under Administration > Devices. The Edge Server will be listed as a device in your organization.

Troubleshooting Onboarding

If you encounter issues during onboarding:

  1. Cannot access the web interface: Verify the container is running and port 3041 is properly mapped
  2. Login fails: Ensure you're using valid ControlCom Connect credentials
  3. Organization not listed: Check that your account has access to at least one organization
  4. Onboarding fails: Check the container logs for detailed error messages: 
    docker-compose logs -f EdgeServer

Re-onboarding

If you need to onboard the Edge Server to a different organization:

  1. Stop the container
  2. Remove the data volume or clear the /data directory
  3. Restart the container
  4. Access the web interface and complete the onboarding process again

Best Practices

Follow these best practices when deploying the ControlCom Edge Server:

Deployment

  • Use Docker Compose for production deployments to ensure consistent configuration
  • Always mount a persistent volume to /data to preserve device onboarding and configuration
  • Run the Edge Server on a dedicated machine or VM for optimal performance
  • Ensure the host machine has adequate resources (minimum 256MB RAM, 1GB for large Production environments)
  • Keep the Edge Server updated by regularly pulling the latest image

Security

  • Restrict access to port 3041 using firewall rules if the Edge Server is exposed to the network
  • Use strong passwords for your ControlCom Connect account
  • Keep the Docker host system updated with security patches
  • Regularly backup the data volume

Monitoring

  • Set appropriate log levels for your environment (info for production, debug for troubleshooting)
  • Monitor container logs regularly for errors or warnings
  • Set up alerts for container restarts or failures
  • Monitor disk space usage for the data volume
  • Track resource utilization (CPU, memory, network) of the Edge Server container

Network Configuration

  • Ensure the Edge Server can reach the ControlCom Connect API endpoints
  • Configure firewall rules to allow outbound HTTPS traffic
  • If using a proxy, configure Docker to use it properly
  • Document the network topology and port mappings
  • Test connectivity to ControlCom Connect before onboarding

Maintenance

  • Schedule regular updates during maintenance windows
  • Test updates in a non-production environment first
  • Keep backups of the data volume before major updates
  • Document your specific configuration and environment variables
  • Maintain a rollback plan in case of update issues

By following these guidelines, you can ensure a reliable and secure deployment of the ControlCom Edge Server that effectively bridges your local IoT infrastructure with the ControlCom Connect platform.

For information on sending data from devices to the Edge Server, see our guides on Sending Data via HTTP and Sending Data via MQTT.

Was this page helpful?