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.