Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lissy93/adguardian-term/llms.txt

Use this file to discover all available pages before exploring further.

Docker is the easiest way to run AdGuardian with no local dependencies. The image is built from a rust:1.90-alpine builder stage that compiles a statically linked musl binary, then copies only that binary and CA certificates into a scratch runtime image — producing a final image of approximately 12 MB.
The -it flags (interactive + TTY) are mandatory for every docker run command. AdGuardian is a TUI application that requires an attached terminal to render its interface. Omitting either flag will result in an immediate exit.
If you need to access AdGuardian in an environment without a terminal — such as a CI runner, a remote server, or a homelab dashboard — see the Web Mode page, which covers running the TUI in a browser via ttyd.

​
Quick start

Pull and run the latest image from Docker Hub with a single command: 
docker run -it lissy93/adguardian
If no environment variables are provided, AdGuardian will interactively prompt you for your AdGuard Home connection details on startup.

​
With credentials

Pass your AdGuard Home instance details as environment variables using -e flags so the app connects immediately without prompting: 
docker run \
  -e "ADGUARD_IP=192.168.180.1" \
  -e "ADGUARD_PORT=3000" \
  -e "ADGUARD_USERNAME=admin" \
  -e "ADGUARD_PASSWORD=bobs-your-uncle" \
  -it lissy93/adguardian
Environment VariableDescriptionDefault
ADGUARD_IPIP address of your AdGuard Home instance—
ADGUARD_PORTPort AdGuard Home is listening on—
ADGUARD_USERNAMEAdGuard Home username—
ADGUARD_PASSWORDAdGuard Home password—
ADGUARD_PROTOCOLProtocol used to contact AdGuard Home (http or https)http
ADGUARD_UPDATE_INTERVALHow often the UI refreshes, in seconds2
ADGUARD_TIMEOUTPer-request timeout when contacting AdGuard Home, in seconds5
ADGUARD_QUERYLOG_LIMITNumber of query log entries fetched per update100

​
Image registries

The same image is published to two registries and kept in sync by the project’s CI pipeline on every release:

Docker Hub

docker run -it lissy93/adguardian

GitHub Container Registry

docker run -it ghcr.io/lissy93/adguardian
Both tags resolve to identical images. Use GHCR if Docker Hub is unavailable in your environment.

​
Building the image yourself

If you want to build the image locally from the source Dockerfile, use docker buildx build: 
docker buildx build -t adguardian .
docker run -it adguardian
The Dockerfile uses a multi-stage build: the rust:1.90-alpine builder stage compiles the binary with cargo build --release, copies it to /adguardian, and the scratch runtime stage picks it up. The build also installs build-base, cmake, perl, and ca-certificates in the builder, so none of those tools end up in the final image. For architectures where the musl/scratch build is not supported (32-bit, ppc64le, s390x), use Dockerfile.full instead, which cross-compiles against a debian:bookworm-slim runtime base: 
docker buildx build -f Dockerfile.full -t adguardian .

​
Docker Compose

To manage AdGuardian alongside other services, add it to a compose.yaml file. The stdin_open and tty options are the Compose equivalents of -it: 
services:
  adguardian:
    image: lissy93/adguardian
    stdin_open: true   # equivalent to -i
    tty: true          # equivalent to -t
    environment:
      - ADGUARD_IP=192.168.180.1
      - ADGUARD_PORT=3000
      - ADGUARD_USERNAME=admin
      - ADGUARD_PASSWORD=bobs-your-uncle
    restart: unless-stopped
Run it with: 
docker compose up

​
Image details

PropertyValue
Runtime basescratch (empty image — no shell, no OS packages)
Builder baserust:1.90-alpine
Binary typeStatically compiled with musl — no shared libraries
CA certsBundled from the Alpine builder (/etc/ssl/certs/ca-certificates.crt) and set via SSL_CERT_FILE
Runs asUID 65534 / GID 65534 (the nobody user)
Entrypoint/adguardian
Approx. size~12 MB

Build docs developers (and LLMs) love

Get started for freeTalk to us