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-v1.0.8
    restart: unless-stopped
    env_file:
      - .env
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun

Startup order with other services

If application containers are defined in the same Compose file as Conflux, declare that they start only after Conflux is healthy so the VeilNet interface is ready before your app runs:

  my-app:
    image: your-app:latest
    network_mode: "container:veilnet-conflux"
    depends_on:
      veilnet-conflux:
        condition: service_healthy

The official veilnet/conflux image ships with a HEALTHCHECK (the veilnet link is up). Compose uses that for service_healthy. If you use a custom image without a health check, add a healthcheck: block on veilnet-conflux yourself, or service_healthy will not behave as intended.

For a full namespace-sharing stack (multiple services per host), see Docker – namespace sharing.

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-v1.0.8
    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