Skip to main content

Docker

Docker Setup

Nogon provides official Docker images for both AMD64 and ARM64 architectures.

The latest image runs as the nonroot user with UID and GID 65532. The examples below use a Docker managed volume so Docker can initialize it with the permissions from the image. If you need to run as root, use the ghcr.io/asciimoo/hister:latest-root image.

Configuring Nogon in a Container

Nogon can be fully configured using environment variables. This is the recommended approach for containerized environments (Docker, Kubernetes, etc.) as it avoids the need to manage configuration files inside the container or mounted volumes.

The container loads /hister/data/config.yml if it exists. Without that file, it uses defaults and environment variables. Relative paths resolve from /hister/data. To require a specific config file, set NOGON_CONFIG (HISTER_CONFIG on older images) or pass --config; a missing file then prevents startup.

If you prefer using a configuration file instead of environment variables, generate a commented reference using Docker:

docker run --rm ghcr.io/asciimoo/hister:latest config create > config.yml

Uncomment each setting you want to activate and its enclosing section, preserving indentation. Leave unrelated settings commented. The listen address example follows the container build’s default. To print all defaults as active YAML values, use config create --full instead. Shell redirection replaces an existing destination file, so choose a new filename to keep an existing configuration.

Basic Docker Compose

For a simple local setup:

services:
  hister:
    image: ghcr.io/asciimoo/hister:latest
    container_name: hister
    restart: unless-stopped
    volumes:
      - hister_data:/hister/data
    ports:
      - 4433:4433

volumes:
  hister_data:

Upgrading an Existing Container

Nogon keeps the existing image address, hister service and container names, hister_data volume, /hister/data mount, and user ID 65532. Keep your current volume or bind mount when updating. If you move or rename the checkout directory, keep the original Compose project name with docker compose -p ORIGINAL_PROJECT so Compose selects the same volume. Do not use down --volumes during an upgrade.

Images that include the rename provide nogon and the compatible hister command. Existing /hister/hister entrypoint overrides also work. Both NOGON_ and HISTER_ configuration variables are accepted; see environment variable precedence. Older Hister images still require their existing command and environment names. Keep those settings until you install an image that includes the rename.

With the repository’s compose.yml, set NOGON_IMAGE to select an image and NOGON_CACHE_IMAGE to select a build cache. The existing HISTER_IMAGE and HISTER_CACHE_IMAGE variables still work. A nonempty Nogon value takes precedence; an empty value falls back to the Hister value, then the current image address.

Docker Compose with External Access

To make Nogon accessible from other devices, use the environment section in your compose.yml:

services:
  hister:
    image: ghcr.io/asciimoo/hister:latest
    container_name: hister
    restart: unless-stopped
    environment:
      - NOGON__SERVER__ADDRESS=0.0.0.0:4433
      - NOGON__SERVER__BASE_URL=http://192.168.1.100:4433 # Use your actual IP/hostname
    volumes:
      - hister_data:/hister/data
    ports:
      - 4433:4433

volumes:
  hister_data:

Docker Compose Behind Reverse Proxy

When running behind a reverse proxy, set the base_url to your public domain:

services:
  hister:
    image: ghcr.io/asciimoo/hister:latest
    container_name: hister
    restart: unless-stopped
    environment:
      - NOGON__SERVER__ADDRESS=0.0.0.0:4433
      - NOGON__SERVER__BASE_URL=https://nogon.example.com # Your public URL
    volumes:
      - hister_data:/hister/data
    ports:
      - 4433:4433

volumes:
  hister_data:

Using a Host Directory

If you want to store the data in a host directory instead of a Docker managed volume, create the directory and give the container user ownership before starting Nogon:

mkdir -p ./data
sudo chown 65532:65532 ./data

Then replace the volume entry with:

volumes:
  - ./data:/hister/data

On a host with SELinux enabled, add the Z option so Docker assigns an appropriate label:

volumes:
  - ./data:/hister/data:Z

Browser Backends with Docker

Browser fetching happens in the nogon index process. The Nogon server can stay in Docker or LXC while you run that command and the browser on your workstation. The official Nogon image does not include Firefox or Chromium.

For the local Compose setup above, install the Nogon binary on the host and start Firefox using the Firefox with BiDi instructions. Then index a page from the host:

nogon --server-url http://127.0.0.1:4433 index 
  --backend bidi 
  --backend-option socket=ws://127.0.0.1:9222/session 
  https://example.com

Or let Nogon launch a locally installed Chromium:

nogon --server-url http://127.0.0.1:4433 index 
  --backend chromedp 
  --backend-option exec_path=/usr/bin/chromium 
  https://example.com

Replace --server-url with your reachable Nogon URL if the server is on another machine, and add --token TOKEN if it requires token authentication. The browser endpoint and the Nogon server address are separate: port 9222 controls Firefox, while port 4433 receives documents.

If you run nogon index inside a container, apply its crawler configuration there. For chromedp, build an image with Chrome or Chromium and its runtime dependencies installed. For bidi, start Firefox separately and make its BiDi endpoint reachable from the indexing process.

With normal container network isolation, 127.0.0.1 refers to the container itself. A browser listening on the host’s loopback interface is not reachable through that address inside a container. Firefox’s Remote Agent listens on loopback, so putting two containers on the same Docker network alone does not expose it. Run Firefox and the indexing command in the same network namespace, or arrange a protected tunnel to the browser’s loopback endpoint. See Docker networking for sharing a container’s network namespace. Keep the browser debugging endpoint private; it provides control of the browser without Nogon’s authentication.

For protocol errors or connection failures, see browser connection troubleshooting.