Arrow FOTA Proxy

Overview

The Arrow FOTA Proxy is an optional server component that caches firmware update files locally on your network. Instead of devices downloading updates directly from the FOTA Cloud, they can download from the Proxy, which reduces internet bandwidth usage and provides faster update delivery for devices on your local network.

The Proxy acts as an intermediary between your devices and the FOTA Cloud storage. When a device requests a firmware update, the Proxy either serves it from its local cache (if available) or downloads it from the cloud and caches it for future requests.

Before You Start

Before setting up the FOTA Proxy Server, ensure you have the following in place:

Hardware Requirements

Resource	Minimum	Recommended
RAM	2 GB	4 GB
Disk Space	10 GB free	50 GB free

Disk Space Considerations

Disk space requirements depend on how many firmware files you expect to cache. Each firmware file can be 0.5–2.5 GB. The Proxy's default cache limit is 50 GB (configurable), and old files are automatically removed when the limit is exceeded.

Software Requirements

Docker or OCI-Compatible Engine

The Proxy runs as an OCI container image, so you need a container engine installed on the host machine. Docker is what we'll be using in our examples, but other OCI-compatible software such as Podman, containerd, or Kubernetes are also valid.

Windows: Docker Desktop for Windows
- Requires Windows 10/11 Pro, Enterprise, or Education (64-bit) with WSL 2 enabled
- Windows Home edition users can also use Docker Desktop with WSL 2 backend
Linux: Docker Engine (Ubuntu, Debian, CentOS, RHEL, etc.)
- Docker Compose: Included with Docker Desktop on Windows/Mac. On Linux, install separately if using Docker Engine (Install Compose)

To verify Docker is installed, open a terminal or command prompt and run:

docker --version
docker compose version

Both commands should print version numbers without errors.

Network Requirements

The host machine must have internet access to:
- Pull the Proxy image
- Connect to the FOTA Cloud API for firmware downloads (on cache misses)
- Connect to the Datalogic Licensing Platform for license validation
The host machine must be reachable on the local network by your Datalogic devices on port 3000 (default, configurable)

License Requirements

A valid Proxy License Key from Datalogic is required for the Proxy to validate against the Datalogic Licensing Platform.

Installation

Step 1: Create Project Files

The Proxy is distributed as a Docker image hosted on GitHub Container Registry at ghcr.io/datalogic/fota-proxy-server:latest. Docker will pull it automatically on first start.

Create a project folder and add the following files:

docker-compose.yml

services:
  fota:
    image: ghcr.io/datalogic/fota-proxy-server:latest
    container_name: fota-proxy-server
    ports:
      - "${PORT:-3000}:${PORT:-3000}"
    env_file:
      - .env
    volumes:
      - fota-cache:/data
    restart: unless-stopped
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://127.0.0.1:${PORT:-3000}/health",
        ]
      interval: 90s
      timeout: 10s
      retries: 3

volumes:
  fota-cache:
    driver: local

.env

# Required — Your license information

# FOTA Proxy License Key
PROXY_LICENSE_KEY=
# Server's MAC Address
MAC_ADDRESS=

# Optional — Customize as needed (defaults shown)
PORT=3000
MAX_CACHE_SIZE_GB=50
LOG_LEVEL=info

Make sure to update PROXY_LICENSE_KEY and MAC_ADDRESS in the .env file with your specific values. See Configuration below for a full explanation of every setting.

Step 2: Start the Proxy

From your project folder, run:

docker compose up -d

The first run will pull the image from GitHub Container Registry, which may take a minute. Subsequent starts are immediate.

Verify It's Running

docker compose ps

You should see the fota-proxy-server container with a status of Up and (healthy).

You can also hit the health endpoint to confirm the server is responding:

http://localhost:3000/health

Step 3: Managing the Proxy

Starting and Stopping

# Stop the proxy (keeps cached data)
docker compose down

# Start the proxy
docker compose up -d

# Restart the proxy
docker compose restart

Viewing Logs

# View recent logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# View last 100 lines
docker compose logs --tail 100

Updating the Proxy

When a new version of the Proxy is available:

# Stop the current container
docker compose down

# Pull the latest image and restart
docker compose pull
docker compose up -d

Data Persistence

Your cached firmware data is preserved across updates because it's stored in a Docker volume, not inside the container.

Configuration

All Proxy settings are controlled through environment variables, defined in your .env file.

Required Settings

These must be set for the Proxy to function in production:

Variable	Description
`PROXY_LICENSE_KEY`	Your Datalogic Proxy license key. Required for license validation.
`MAC_ADDRESS`	The MAC address of the machine running the Proxy. Used for license binding.

Optional Settings

These have sensible defaults but can be adjusted for your environment.

Variable	Default	Description
`PORT`	`3000`	The port the Proxy listens on.
`MAX_CACHE_SIZE_GB`	`50`	Maximum total size of cached firmware files in gigabytes. When exceeded, the least recently used firmware is evicted.
`FIRMWARE_LIST_TTL_MS`	`3600000` (1 hour)	Time until the cached firmware lists are considered stale and the Proxy refreshes.
`LOG_LEVEL`	`info`	Logging verbosity. Options: `error`, `warn`, `info`, `debug`. Use `debug` for troubleshooting.

Network Setup

Once the Proxy is running, you need to configure your Datalogic devices to point to where it's located on your local network.

Finding the Proxy's Address

The Proxy needs to be reachable by all devices on your network. You'll need the IP address (or hostname) of the machine running the Proxy.

On Windows:

Open PowerShell and run:

ipconfig

Look for the IPv4 Address under your active network adapter (e.g., 192.168.1.42).

On Linux:

hostname -I
# or
ip addr show

Your Proxy URL will be:

http://<proxy-ip>:3000

For example: http://192.168.1.42:3000 (assuming you didn't change from the default port)

Static IP Assignment

Consider assigning a static IP or a DNS hostname to the Proxy machine so the address doesn't change if DHCP assigns a new IP.

Configuring Devices to Use the Proxy

Devices need to be configured to send firmware update requests to the Proxy instead of the FOTA Cloud. On the device, make sure the Transport mode is set to Arrow Proxy. Then, set the Firmware server to:

http://<proxy-ip>:3000

Additional details on setting the Proxy address on the device can be found here.

Firewall Considerations

On the Proxy Host

Ensure the Proxy's port (default 3000) is open for inbound connections from your local network.

Outbound from the Proxy Host

The Proxy machine needs outbound internet access to reach:

Destination	Purpose	URL
FOTA Cloud API	Download firmware on cache misses	`https://device-api.datalogic.kilpitek.com`
GitHub	Fetch the firmware list JSON	`https://github.com`
Datalogic Licensing Platform	Validate the Proxy license	`https://api.datalogic.com`

Overview​

Before You Start​

Hardware Requirements​

Software Requirements​

Network Requirements​

License Requirements​

Installation​

Step 1: Create Project Files​

Step 2: Start the Proxy​

Verify It's Running​

Step 3: Managing the Proxy​

Starting and Stopping​

Viewing Logs​

Updating the Proxy​

Configuration​

Required Settings​

Optional Settings​

Network Setup​

Finding the Proxy's Address​

Configuring Devices to Use the Proxy​

Firewall Considerations​

On the Proxy Host​

Outbound from the Proxy Host​