ControlCom Edge Server

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

Pre-requisites

The Edge Server runs as a Docker container, so you need either Docker Engine (Linux servers) or Docker Desktop (macOS, Windows, or Linux workstations) installed on the host machine.

See Get Docker for installation instructions for your platform.

Minimum Requirements

Quick Start

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

Follow along with the video walkthrough above, or continue reading for detailed instructions:

docker run -p 3041:3041 public.ecr.aws/controlcomtech/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 https://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.

TimescaleDB is optional — attach it when you want a local timeseries store; skip it otherwise. Pick the setup that matches what you need:

• All-in-One Setup — Edge Server plus a local TimescaleDB in the same compose file. Best when you want local timeseries storage with one command to bring up the whole stack.
• Edge Server Only — just the Edge Server, minimal configuration.

All-in-One Setup

This bundles the Edge Server with a local TimescaleDB instance so the entire timeseries store lives on the same host.

Step 1: Create the Docker Compose File

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

services:
  timescale:
    image: timescale/timescaledb-ha:pg18.3-ts2.25.2
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: '10m'
        max-file: '3'
    mem_limit: 2GB
    cpus: 2
    network_mode: host
    environment:
      POSTGRES_PASSWORD: test
    volumes:
      - 'timescaledata:/home/postgres/pgdata'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 5s
      retries: 10
    command: -c max_connections=30 -c shared_buffers=512MB -c effective_cache_size=1536MB -c maintenance_work_mem=128MB -c checkpoint_completion_target=0.9 -c wal_buffers=16MB -c default_statistics_target=100 -c random_page_cost=1.1 -c effective_io_concurrency=200 -c work_mem=8738kB -c huge_pages=off -c min_wal_size=1GB -c max_wal_size=4GB

  edge-server:
    image: 'public.ecr.aws/controlcomtech/edge-server:latest'
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: '10m'
        max-file: '3'
    depends_on:
      timescale:
        condition: service_healthy
    network_mode: host
    environment:
      - POSTGRES_HOSTNAME=localhost
      - POSTGRES_PASSWORD=test
    volumes:
      - 'edgeserver:/data'
    mem_limit: 384m

volumes:
  timescaledata:
    driver: local
  edgeserver:
    driver: local

This file is ready to run as-is — both services share a user-defined controlcom bridge network, so the Edge Server reaches Timescale at the service name timescale (port 5432) and waits for it to pass its pg_isready healthcheck before starting. Change POSTGRES_PASSWORD from the test default before any non-local deployment, and update it in both services so they stay in sync.

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 edge-server service listed as Up.

To view the logs:

docker-compose logs -f edge-server

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

Edge Server Only

The minimal compose — just the Edge Server, no database. Use this when you don't need local timeseries storage, or you want to wire the Edge Server up to your own database separately.

services:
  edge-server:
    image: 'public.ecr.aws/controlcomtech/edge-server:latest'
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: '10m'
        max-file: '3'
    ports:
      - '3040:3040'
      - '3041:3041'
      - '5443:5443'
      - '8443:8443'
      - '8883:8883'
    volumes:
      - 'edgeserver:/data'
    mem_limit: 384m

volumes:
  edgeserver:
    driver: local

Start it the same way as the all-in-one setup:

docker-compose up -d

Port Reference

The Edge Server publishes the following ports. Adjust the host-side bindings in your compose file to match your network policy.

Configuration

The Edge Server supports optional environment variables for customization. Add these to your docker-compose.yml file under the edge-server service's environment section alongside the required variables shown above:

    environment:
      - POSTGRES_HOSTNAME=timescale
      - POSTGRES_DATABASE=postgres
      - POSTGRES_PASSWORD=test
      - DEVICE_TIMEZONE=America/New_York
      - LOG_LEVEL=info

Available Environment Variables

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:
  - 'edgeserver:/data'

This creates a Docker-managed volume named edgeserver 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>_edgeserver

Backup the data volume:

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

Restore from backup:

docker run --rm -v <project-directory>_edgeserver:/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:

https://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 edge-server
   

   CopyCopied!

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

• Port Binding: Bind to localhost only (127.0.0.1:3041:3041) unless network access is required. Using 3041:3041 exposes to all networks including WAN if the host is internet-connected. Only expose to secure network subnets by binding to a specific subnet IP (<subnet-ip>:3041:3041)
• Firewall Rules: Restrict access to port 3041 using firewall rules if the Edge Server must be exposed to the network
• Authentication: Use strong passwords for your ControlCom Connect account
• System Updates: Keep the Docker host system updated with security patches
• Backups: Regularly backup the data volume to prevent data loss

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.