Run verifyngo in Docker with docker run or Docker Compose

verifyngo ships as a minimal Docker image built on distroless/static-debian12. There is no shell, no package manager, and no unnecessary tooling — just the compiled binary. This guide covers running it with docker run and with Docker Compose, including how to persist state and serve custom static files.

Quick start with docker run

The fastest way to get verifyngo running is a single docker run command. Mount your config.json into the container and expose port 8080:

docker run -d \
  --name verifyngo \
  -p 8080:8080 \
  -v $(pwd)/config.json:/config.json:ro \
  ghcr.io/chocolatemoo53/verifyngo:latest

Flag	What it does
`-d`	Run the container in the background (detached mode).
`--name verifyngo`	Give the container a memorable name so you can reference it with `docker logs`, `docker stop`, etc.
`-p 8080:8080`	Bind the container’s port `8080` to port `8080` on your host.
`-v $(pwd)/config.json:/config.json:ro`	Bind-mount your local `config.json` into the container at `/config.json`, read-only. The container reads from this path by default.
`ghcr.io/chocolatemoo53/verifyngo:latest`	Pull the latest published image from the GitHub Container Registry.

Docker Compose

For production deployments, Docker Compose gives you a repeatable, version-controlled setup. The following file is based on the project’s example and includes a named volume for persistent state:

docker-compose.yml

services:
  verifyngo:
    image: ghcr.io/chocolatemoo53/verifyngo:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.json:/config.json:ro
      - ./static:/static:ro
      # Uncomment one of the following to load a rules file or policy file:
      # - ./rules.txt:/rules.txt:ro
      # - ./policy.yml:/policy.yml:ro
      - verifyngo-data:/data
    environment:
      - TZ=UTC
    restart: unless-stopped

volumes:
  verifyngo-data:

Bring the stack up with:

docker compose up -d

To tail logs in real time:

docker compose logs -f verifyngo

Persisting state

By default, verifyngo keeps its ban and verification state in memory. When the container restarts, that state is lost and previously-banned clients can connect again. To persist state across restarts, mount a named volume at /data and point store.file.path at a file inside it:

config.json

"store": {
  "backend": "memory",
  "file": {
    "path": "/data/store.json",
    "save_interval": "30s"
  }
}

With this configuration verifyngo flushes its in-memory state to /data/store.json every 30 seconds and reloads it on startup. The verifyngo-data named volume in the Compose example above satisfies the /data mount.

Serving custom static files

You can supply a custom logo, stylesheet, or other assets by mounting a local directory into the container and telling verifyngo where to find it with the static_dir config key. Those files are then reachable under /static/ and can be referenced in your branding config. Mount the directory when you run the container:

docker run -d \
  -v $(pwd)/config.json:/config.json:ro \
  -v $(pwd)/static:/static:ro \
  -p 8080:8080 \
  ghcr.io/chocolatemoo53/verifyngo:latest

Then point static_dir at the mount path in your config:

config.json

{ "static_dir": "/static" }

You can then reference files in your branding block like this:

config.json

"branding": {
  "logo_url": "/static/logo.svg",
  "css_url": "/static/custom.css"
}

The Docker image runs as a non-root user (nonroot:nonroot). Make sure any files and directories you bind-mount into the container are readable by this user. On Linux, chmod o+r on the files (or o+rx on directories) is the simplest fix if you run into permission errors.

Get Started

Configuration

Guides

Reference

Run verifyngo in Docker with docker run or Docker Compose

Quick start with docker run

Docker Compose

Persisting state

Serving custom static files

​Quick start with docker run

​Docker Compose

​Persisting state

​Serving custom static files

Quick start with docker run

Docker Compose

Persisting state

Serving custom static files