Skip to content
Klutch.sh Docs

Deploying an AdGuard Home App

Introduction

AdGuard Home is an all-in-one network-wide DNS-level ad blocker and privacy protection system. It acts as a DNS server that filters ads, trackers, and malicious domains before they ever reach your devices, while providing an intuitive web dashboard for configuration, statistics, and security controls.

Deploying AdGuard Home on Klutch.sh with a Dockerfile gives you a managed, cloud-hosted DNS filtering service with a secure web UI. This guide walks through creating a Docker-based AdGuard Home setup, configuring volumes for persistent settings and statistics, pushing your project to GitHub, and deploying it via the Klutch.sh dashboard at klutch.sh/app.

Prerequisites

Before you deploy AdGuard Home on Klutch.sh, you’ll need:

  • A Klutch.sh account
  • A GitHub account (GitHub is the only supported git source)
  • Docker installed locally for testing (optional but recommended)
  • Basic understanding of DNS and network configuration

Project Setup for AdGuard Home

1. Create a Project Directory

Create and initialize a project directory for your AdGuard Home deployment:

Terminal window
mkdir adguard-home-klutch
cd adguard-home-klutch
git init

2. AdGuard Home Directories

AdGuard Home persists its configuration and runtime data under two primary directories:

  • Configuration: /opt/adguardhome/conf
  • Data & statistics: /opt/adguardhome/work

On Klutch.sh, you’ll mount these paths as persistent volumes so settings and DNS statistics survive redeploys and restarts.

Creating a Dockerfile for AdGuard Home

Klutch.sh automatically detects a Dockerfile in your repository root and uses it for deployment. You don’t manually select Docker as a deployment option in the UI and you don’t specify a Dockerfile path—detection is automatic when a Dockerfile is present.

Create a file named Dockerfile in the project root:

FROM adguard/adguardhome:latest


# AdGuard Home container already expects:
#   - /opt/adguardhome/conf for configuration
#   - /opt/adguardhome/work for runtime data


WORKDIR /opt/adguardhome


# Expose the web UI (3000) and DNS server ports (53 TCP)
# Note: Klutch.sh exposes TCP traffic; DNS over UDP is not exposed through TCP routing.
EXPOSE 3000 53


# The container’s default entrypoint starts AdGuard Home
CMD ["/AdGuardHome", "-s", "run"]

Dockerfile Notes

  • The web dashboard runs on port 3000 by default; this will be your internal port for HTTP traffic on Klutch.sh.
  • DNS usually uses port 53 (TCP/UDP). While this Dockerfile exposes port 53, Klutch.sh’s TCP routing is best suited for HTTP access and TCP-based connections; exposing DNS publicly may require additional network considerations.
  • Configuration and data directories (/opt/adguardhome/conf and /opt/adguardhome/work) will be mounted as persistent volumes on Klutch.sh.

Optional: Local Testing with Docker

You can validate your AdGuard Home setup locally before deploying to Klutch.sh:

Terminal window
# Build the image
docker build -t adguard-home-klutch .


# Run the container locally
docker run -d \
  --name adguard-home-test \
  -p 3000:3000 \
  -p 53:53/tcp \
  -v "$(pwd)/conf:/opt/adguardhome/conf" \
  -v "$(pwd)/work:/opt/adguardhome/work" \
  adguard-home-klutch

Then open http://localhost:3000 to access the AdGuard Home setup wizard and dashboard.

For more advanced local setups, you can use Docker Compose to run AdGuard Home alongside other services. Docker Compose is strictly for local use; Klutch.sh does not deploy via Docker Compose.

Pushing Your AdGuard Home Project to GitHub

Once your Dockerfile is ready (and optional local directories or docs are in place), push your project to GitHub:

Terminal window
git add .
git commit -m "Initial AdGuard Home Docker setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/your-username/adguard-home-klutch.git
git push -u origin main

Klutch.sh will use this GitHub repository as the source for building and deploying your AdGuard Home app.

Creating an AdGuard Home App on Klutch.sh

With your repository in place, you can create and configure the app in the Klutch.sh dashboard.

Connect the Repository

  1. Sign in to klutch.sh/app.
  2. Go to Create Project and give your project a name like adguard-home.
  3. Navigate to Create App and:
    • Select GitHub as the git source.
    • Choose your AdGuard Home repository and the branch to deploy (for example, main).

Klutch.sh will automatically detect the Dockerfile in the repository root and use it for deployment.

Traffic Type and Internal Port

  • Traffic Type: Select HTTP (for accessing the AdGuard Home web dashboard).
  • Internal Port: Set to 3000, which matches the web UI port exposed by your Dockerfile.

This setup routes HTTP requests to the AdGuard Home dashboard inside the container.

If you experiment with DNS access from specific clients using TCP, you can also configure another app with TCP traffic and appropriate internal port mapping, bearing in mind that DNS relies heavily on UDP and may have limitations when exposed through TCP-only routing.

Environment Variables on Klutch.sh

AdGuard Home can run with its defaults, but you may want to configure:

  • TZ – your timezone (for example, UTC or America/New_York) for accurate log timestamps.

If you deploy without a Dockerfile and rely on Nixpacks, you can customize the build and start behavior using environment variables:

  • BUILD_COMMAND – override the default build command Nixpacks uses.
  • START_COMMAND – override the default start command Nixpacks runs.

Set these environment variables in the Klutch.sh dashboard when customizing Nixpacks behavior for non-Docker deployments.

Attaching Persistent Volumes

To preserve AdGuard Home configuration, DNS logs, and statistics across redeploys, you should attach persistent volumes for both configuration and data directories.

In the app’s Storage/Volumes section, add:

  • Configuration Volume

    • Mount path: /opt/adguardhome/conf
    • Size: Small (for example, 1 GiB) is usually sufficient for configuration files.

  • Data & Statistics Volume

    • Mount path: /opt/adguardhome/work
    • Size: Choose based on how much logging, statistics, and history you plan to retain (for example, 5 GiB or more).

These volumes ensure your AdGuard Home setup wizard choices, custom blocklists, clients, and statistics are preserved even when the container is rebuilt or restarted.

Sample Usage: Accessing the AdGuard Home API

AdGuard Home exposes a JSON HTTP API for automating configuration changes and retrieving statistics. After you deploy to Klutch.sh, your app will be available at a URL like:

https://example-app.klutch.sh

You can send authenticated requests to endpoints under /control/.

JavaScript Example: Fetching Statistics

async function fetchAdGuardStats() {
  const response = await fetch('https://example-app.klutch.sh/control/stats', {
    // If you require authentication, include the appropriate headers or cookies here.
    // headers: {
    //   'Authorization': 'Basic BASE64_ENCODED_CREDENTIALS',
    // },
  });


  if (!response.ok) {
    throw new Error(`Failed to fetch AdGuard Home stats: ${response.status}`);
  }


  const stats = await response.json();
  console.log('AdGuard Home stats:', stats);
}


fetchAdGuardStats().catch((err) => {
  console.error('Error loading AdGuard Home stats', err);
});

You can adapt this pattern in dashboards or monitoring tools to display blocked queries, top domains, or client usage based on the AdGuard Home API response.

Verifying Your Deployment

After your first deployment on Klutch.sh completes:

  1. Open your app URL:

    https://example-app.klutch.sh

  2. Confirm that:

    • The AdGuard Home setup page or dashboard loads.
    • Any changes you make in the web UI (such as adding custom blocklists or clients) remain after restarting the app, verifying that your /opt/adguardhome/conf and /opt/adguardhome/work volumes are working correctly.

If you plan to route DNS queries through this instance for select devices or networks, configure them to use the app’s DNS endpoint carefully, testing with non-critical traffic first.

Troubleshooting

Dashboard Not Loading

  • Verify that the app’s Traffic Type is set to HTTP.
  • Confirm that the internal port is 3000 and matches the Dockerfile’s exposed port.
  • Check deployment logs in the Klutch.sh dashboard for AdGuard Home startup errors.

Settings or Logs Not Persisting

  • Ensure persistent volumes are attached with mount paths:
    • /opt/adguardhome/conf
    • /opt/adguardhome/work
  • Check that the selected volume sizes are sufficient for configuration and log retention.
  • Confirm the container has write access to these directories.

API Calls Failing

  • Make sure you’re calling the correct URL (for example, https://example-app.klutch.sh/control/stats).
  • If you’ve enabled authentication in AdGuard Home, ensure you include the required headers or cookies.
  • Inspect the AdGuard Home and Klutch.sh logs for HTTP status codes or error messages.

Deploying an AdGuard Home app on Klutch.sh with a Dockerfile gives you a powerful, network-wide ad blocking and privacy solution hosted on infrastructure you control. With a simple Dockerfile, correctly configured internal port, and persistent volumes for configuration and data, you can run a reliable AdGuard Home instance on Klutch.sh and manage DNS filtering for your devices from an easy-to-use web dashboard.