Docker

Prerequisites

• Docker and Docker Compose installed
• A VeilNet registration token
• Network access to VeilNet Guardian (default: https://guardian.veilnet.app) and standard outbound HTTPS

Overview

VeilNet Conflux runs as a container with:

• A TUN device (/dev/net/tun) for virtual networking
• NET_ADMIN capability to configure networking inside the container namespace
• Environment-variable based configuration

You configure the container using environment variables (either via .env or directly in Compose).

Note TUN device created by VeilNet Conflux is a virtual network interface that exists within the container namespace. It is not visible on the host network, unless you enable host network mode.

Docker Compose (recommended)

Create a docker-compose.yml like:

services:
  veilnet-conflux:
    container_name: veilnet-conflux
    image: veilnet/conflux:beta
    restart: unless-stopped
    env_file:
      - .env
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun

Environment variables

Create a .env file next to your docker-compose.yml.

Required

# Required: registration token (keep secret)
VEILNET_REGISTRATION_TOKEN=<YOUR_REGISTRATION_TOKEN>

Common optional settings

# Optional: Guardian URL (defaults to https://guardian.veilnet.app)
VEILNET_GUARDIAN=https://guardian.veilnet.app

# Optional: human-readable identifier
VEILNET_CONFLUX_TAG=dev-server-1

# Optional: the VeilNet IP for this Conflux instance (this is the IP other VeilNet
# devices/services will use to reach workloads on this node).
#
# This is NOT your physical host IP. Example format depends on your VeilNet realm,
# e.g. 10.128.0.5
VEILNET_CONFLUX_IP=<YOUR_VEILNET_IP>

# Optional: rift mode (default false)
VEILNET_CONFLUX_RIFT=false

# Optional: portal mode (default false)
VEILNET_CONFLUX_PORTAL=false

Optional: tracing (OTLP)

VEILNET_TRACER=false
VEILNET_OTLP_ENDPOINT=
VEILNET_OTLP_USE_TLS=false
VEILNET_OTLP_INSECURE=false
VEILNET_OTLP_CA_CERT=
VEILNET_OTLP_CLIENT_CERT=
VEILNET_OTLP_CLIENT_KEY=

Optional: JWT/JWKS registration fields

If your deployment uses JWT-based node auth, these are supported:

VEILNET_CONFLUX_JWT=
VEILNET_CONFLUX_JWKS_URL=
VEILNET_CONFLUX_AUDIENCE=
VEILNET_CONFLUX_ISSUER=

Optional: taints

Taints constrain which Conflux instances can communicate (identity affinity). For two Conflux instances to communicate, their taints must be compatible.

For “multi-host service mesh” deployments, you typically want at least one shared taint across all participating hosts (required for connectivity under taint-based affinity).

Provide a comma-separated list of simple labels (e.g. prod, us-east). You cannot use = in a taint.

VEILNET_CONFLUX_TAINTS=prod,us-east

Deploy

docker-compose up -d

Verify

docker ps | grep veilnet-conflux
docker logs veilnet-conflux -f

For multi-host Docker with namespace sharing (app containers in the same network namespace as Conflux on each host), see Docker – namespace sharing.

Optional: host network mode (“host agent” style)

If you want the container to behave like a host-level agent using the host network stack, you can enable host networking:

services:
  veilnet-conflux:
    container_name: veilnet-conflux
    image: veilnet/conflux:beta
    restart: unless-stopped
    env_file:
      - .env
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    network_mode: host

This mode is useful when you want the Conflux deployment to resemble a “system service” on that machine, but it is not required for the multi-host namespace-sharing pattern (see Docker – namespace sharing).

Updating

docker-compose pull
docker-compose up -d

Stopping

docker-compose down