🔒 Ad-Blocking Toolkit

← Back to Documentation

Documentation

Docker Guide

This guide covers using Docker for development with the ad-blocking toolkit.

Docker Development Environment

The repository includes a pre-configured Docker environment with all necessary dependencies for all compilers (TypeScript, .NET, Python, Rust) and tools.

Dockerfile.warp

FROM mcr.microsoft.com/dotnet/sdk:10.0-noble

# Build arguments for version control
ARG DENO_VERSION=2.x
ARG RUST_VERSION=stable

# Includes installation of:
# - Deno 2.x
# - Python 3.12 with pip
# - Rust stable toolchain
# - PowerShell 7
# - yq (YAML processor)
# - hostlist-compiler (via Deno npm compatibility)

WORKDIR /workspace

Included Components

Component Version Purpose
.NET SDK 10.0 .NET compiler, API client
Deno 2.x TypeScript compiler, hostlist-compiler
Python 3.12 Python compiler
Rust Stable Rust compiler
PowerShell 7.x PowerShell scripts and modules
Git Latest Version control
yq Latest YAML processing for shell scripts
hostlist-compiler Latest Via Deno npm compatibility
Ubuntu 24.04 (Noble) Base OS

Pre-installed Tools

  • Deno packages: @adguard/hostlist-compiler (via npm: specifier)
  • Python packages: pytest, pytest-cov, mypy, ruff, pyyaml, tomlkit
  • Rust components: clippy, rustfmt
  • PowerShell modules: Pester, PSScriptAnalyzer

Building the Docker Image

Standard Build

docker build -f Dockerfile.warp -t ad-blocking-dev .

With Build Arguments

docker build -f Dockerfile.warp \
  --build-arg DENO_VERSION=2.x \
  --build-arg RUST_VERSION=stable \
  -t ad-blocking-dev:custom .

Multi-platform Build

docker buildx build -f Dockerfile.warp \
  --platform linux/amd64,linux/arm64 \
  -t ad-blocking-dev:multiarch .

Running the Container

Interactive Mode

docker run -it -v $(pwd):/workspace ad-blocking-dev

With Environment Variables

docker run -it \
  -v $(pwd):/workspace \
  -e "AdGuard__ApiKey=your-api-key" \
  -e "DEBUG=1" \
  ad-blocking-dev

Detached Mode

docker run -d \
  -v $(pwd):/workspace \
  --name ad-blocking-container \
  ad-blocking-dev \
  sleep infinity

Then execute commands:

docker exec ad-blocking-container deno task compile

Docker Compose

The repository includes a docker-compose.yml for multi-service orchestration.

Available Services

Service Description Profile
dev Main development environment default
typescript-compiler TypeScript rules compiler compile
dotnet-compiler .NET rules compiler compile
python-compiler Python rules compiler compile
rust-compiler Rust rules compiler compile
test Run all tests test
console-ui AdGuard Console UI console

Basic Usage

# Start main development environment
docker compose up -d dev

# Enter the container
docker compose exec dev bash

# Stop all services
docker compose down

Running Specific Services

# Run TypeScript compiler
docker compose --profile compile run --rm typescript-compiler

# Run all compilers
docker compose --profile compile up

# Run all tests
docker compose --profile test run --rm test

# Run AdGuard Console UI
docker compose --profile console run --rm console-ui

Environment Variables

Create a .env file in the project root:

# .env
DEBUG=1
ADGUARD_API_KEY=your-api-key-here

Development Workflow

Initial Setup (Inside Container)

# TypeScript compiler (Deno caches dependencies automatically)
cd /workspace/src/rules-compiler-typescript
deno cache src/mod.ts

# .NET projects
cd /workspace/src/rules-compiler-dotnet
dotnet restore RulesCompiler.slnx

cd /workspace/src/adguard-api-dotnet
dotnet restore src/AdGuard.ApiClient.sln

# Python compiler
cd /workspace/src/rules-compiler-python
pip install -e ".[dev]"

# Rust compiler
cd /workspace/src/rules-compiler-rust
cargo build

Compiling Filter Rules

# TypeScript (Deno)
cd /workspace/src/rules-compiler-typescript
deno task compile

# .NET
cd /workspace/src/rules-compiler-dotnet
dotnet run --project src/RulesCompiler.Console

# Python
cd /workspace/src/rules-compiler-python
rules-compiler

# Rust
cd /workspace/src/rules-compiler-rust
cargo run --release

# Shell (Bash)
/workspace/src/rules-compiler-shell/compile-rules.sh

# PowerShell
cd /workspace
pwsh -Command "Import-Module ./src/adguard-api-powershell/Invoke-RulesCompiler.psm1; Invoke-RulesCompiler"

Running Tests

# TypeScript tests (Deno)
cd /workspace/src/rules-compiler-typescript
deno task test

# .NET tests
cd /workspace/src/rules-compiler-dotnet
dotnet test RulesCompiler.slnx

# Python tests
cd /workspace/src/rules-compiler-python
pytest

# Rust tests
cd /workspace/src/rules-compiler-rust
cargo test

# PowerShell tests
cd /workspace
pwsh -Command "Invoke-Pester -Path ./src/adguard-api-powershell/Tests/"

# Or run all tests via docker compose
docker compose --profile test run --rm test

Warp Environment

For Warp terminal users, a pre-built environment is available.

Environment Details

Property Value
Docker Image jaysonknight/warp-env:ad-blocking
Environment ID Egji4sZU4TNIOwNasFU73A

Using with Warp

# The environment automatically runs these setup commands:
cd ad-blocking/src/rules-compiler-typescript && deno cache src/mod.ts
cd ad-blocking/src/adguard-api-dotnet && dotnet restore

CI/CD with Docker

GitHub Actions Example

name: Build with Docker

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -f Dockerfile.warp -t ad-blocking-dev .

      - name: Run TypeScript tests
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            ad-blocking-dev \
            bash -c "cd /workspace/src/rules-compiler-typescript && deno task test"

      - name: Run .NET tests
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            ad-blocking-dev \
            bash -c "cd /workspace/src/rules-compiler-dotnet && dotnet restore && dotnet test"

      - name: Run Python tests
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            ad-blocking-dev \
            bash -c "cd /workspace/src/rules-compiler-python && pip install -e '.[dev]' && pytest"

      - name: Run Rust tests
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            ad-blocking-dev \
            bash -c "cd /workspace/src/rules-compiler-rust && cargo test"

Troubleshooting

Permission Issues

If you encounter permission issues with mounted volumes:

# Run as current user
docker run -it -v $(pwd):/workspace -u $(id -u):$(id -g) ad-blocking-dev

Deno Cache Issues

If Deno cache has issues between host and container:

# Clear Deno cache and re-cache dependencies
docker run -it -v $(pwd):/workspace ad-blocking-dev bash -c "
  rm -rf /root/.deno/deps
  cd /workspace/src/rules-compiler-typescript
  deno cache src/mod.ts
"

.NET Restore Failures

If .NET restore fails:

docker run -it -v $(pwd):/workspace ad-blocking-dev bash -c "
  cd /workspace/src/rules-compiler-dotnet
  dotnet nuget locals all --clear
  dotnet restore RulesCompiler.slnx
"

Cargo/Rust Issues

If Rust compilation fails:

docker run -it -v $(pwd):/workspace ad-blocking-dev bash -c "
  cd /workspace/src/rules-compiler-rust
  cargo clean
  cargo build
"

Container Won't Start

Check if the image exists:

docker images | grep ad-blocking-dev

Rebuild if necessary:

docker build --no-cache -f Dockerfile.warp -t ad-blocking-dev .

Volume Caching Issues

Reset named volumes if caching causes problems:

# Remove all ad-blocking volumes
docker volume rm ad-blocking-deno-cache ad-blocking-node-web ad-blocking-cargo-registry ad-blocking-cargo-git ad-blocking-nuget

# Or remove all unused volumes
docker volume prune