Initialize Synentra with Docker

You can set up a Synentra environment with Docker in two ways:

• Automated setup
  A single synctl init --docker command that handles the image, container, volumes, and port mapping for you.

• Manual setup
  Full control over the Docker run command, environment variables, volume mounts, and sidecar services.

Both approaches result in a running Synentra gateway on your machine.

Linux only

Docker-based initialization is currently supported only on Linux. Windows users should initialize Synentra using the native binary:

synctl init

Automated Setup with CLI

The synctl init --docker command automatically downloads the appropriate Synentra container image for your platform, creates a Docker container, configures persistent storage, and starts the gateway.

Prerequisites

• You're running a Linux distribution or WSL (Windows SubSystem Linux).
• Docker Engine is installed.
• The Docker daemon is running.
• Your user has permission to run Docker commands.

Step 1: Open a Terminal

Open your preferred Linux terminal.

If your Docker installation requires elevated privileges, prefix the commands with sudo.

Step 2: Initialize Synentra

Run:

synctl init --docker

The CLI automatically:

• Detects the correct Docker image for your platform.
• Downloads the latest Synentra image.
• Creates a persistent data directory.
• Creates the Docker container.
• Maps port 7080 to the host.
• Starts the Synentra gateway.

When initialization completes successfully, the gateway is immediately ready to use.

Using a Specific Version

To initialize a specific release:

synctl init --docker --version 1.4.2

Customizing the Deployment

You can customize the container during initialization.

Change the container name

synctl init --docker --container-name my-synentra

Use a different port

synctl init --docker --port 8080

Use a custom data directory

synctl init --docker --mount /opt/synentra/data

Change the container data path

synctl init --docker --container-path /app/storage

Verify the Deployment

Verify that the CLI is installed:

synctl --version

Verify that the gateway container is running:

docker ps

You should see a running container similar to:

synentra-gateway

Troubleshooting

Docker is not available

If Docker is not installed or the Docker daemon is not running, initialization will fail.

Start Docker and rerun:

synctl init --docker

Unsupported platform

Docker initialization is currently available only on Linux.

On Windows, initialize Synentra using the native installation:

synctl init

Reinitializing

Running the command again automatically replaces any existing Synentra container with the same name while preserving your mounted data directory.

Manual Docker Setup

The Synentra CLI provides the recommended Docker initialization workflow. However, you can also run Synentra manually using Docker.

This is useful for:

• Custom Docker deployments.
• Docker Compose environments.
• Production infrastructure.
• Kubernetes or container orchestration setups.

Pull the Synentra Image

Synentra images are published to GitHub Container Registry (GHCR).

Pull the latest image:

docker pull ghcr.io/synentra/synentra:latest

The latest tag is a multi-architecture image. Docker automatically selects the correct image variant for your system.

Supported platforms:

Tag	Architecture
ghcr.io/synentra/synentra:1.x.x-linux-amd64	amd64
ghcr.io/synentra/synentra:1.x.x-linux-arm64	arm64

See the available Docker images

The container exposes port:

7080

Run Synentra Container

A minimal local deployment:

docker run -d \
  --name synentra \
  -p 7080:7080 \
  -v $(pwd)/data:/data \
  -v $(pwd)/policies:/policies \
  -e System__Storage__Database__Providers__Sqlite__ConnectionString="Data Source=/data/synentra.db" \
  -e Policy__Providers__Internal__Directory="/policies" \
  ghcr.io/synentra/synentra:latest

This creates:

• A Synentra gateway container.
• Persistent storage for the database.
• A mounted policy directory.
• HTTP access on port 7080.

Verify the container:

docker ps

Expected output:

synentra

Test the gateway:

curl http://localhost:7080/health

Expected response:

{
  "status": "Healthy",
  "healthCheckDuration": "00:00:00.0123456"
}

Persistent Storage

For production deployments, mount persistent volumes:

Container Path	Purpose
/data	Database storage
/policies	Policy definitions
/app/logs	Application logs
/certs	TLS certificates

Docker Compose

For deployments requiring additional services such as Redis, Seq, or OPA, use Docker Compose.

services:
  synentra:
    image: ghcr.io/synentra/synentra:latest
    container_name: synentra
    ports:
      - "7080:7080"
    environment:
      System__Storage__Database__DefaultProvider: Sqlite
      System__Storage__Database__Providers__Sqlite__ConnectionString: "Data Source=/data/synentra.db"
      Policy__Enabled: "true"
      Policy__DefaultProvider: Internal
      Policy__Providers__Internal__Directory: /policies
    volumes:
      - synentra-data:/data
      - ./policies:/policies:ro
    restart: unless-stopped

volumes:
  synentra-data:

Start:

docker compose up -d

Configuration

tip

Docker configuration uses ASP.NET Core environment variable syntax. Configuration sections are separated using double underscores (__).

Example:

System__Server__Http__Port=7080

maps to:

{
  "System": {
    "Server": {
      "Http": {
        "Port": 7080
      }
    }
  }
}

See the Configuration reference for all available settings.