GuidesQuick Start

Quick Start

Get the Bloqr Compiler running in minutes with Docker, Deno, or Cloudflare Workers.

Get the Bloqr Compiler up and running in minutes with your preferred runtime.

Prerequisites

  • Git installed locally
  • Docker path: Docker + Docker Compose
  • Deno / Workers path: Deno installed (deno --version)
  • Workers deploy: Cloudflare account + Wrangler auth (deno task wrangler login)

Installation Methods

Quick Start

Clone the repository

git clone https://github.com/bloqr-systems/bloqr-compiler.git
cd bloqr-compiler

Start with Docker Compose

docker compose up -d

Access the application

SurfaceURL
Web UIhttp://localhost:8787
API Documentationhttp://localhost:8787/api
Test Interfacehttp://localhost:8787/test.html
Metricshttp://localhost:8787/metrics

That's it! The compiler is now running. For advanced configuration see the sections below.

Managing the Container

View logs

docker compose logs -f

Stop the container

docker compose down

Restart the container

docker compose restart

Update the container

git pull
docker compose down
docker compose build --no-cache
docker compose up -d

Configuration

Environment Variables

Copy the example environment file and customize:

cp .env.example .env
# Edit .env with your preferred settings

Available variables:

  • COMPILER_VERSION: Version identifier (default: 0.6.0)
  • PORT: Server port (default: 8787)
  • DENO_DIR: Deno cache directory (default: /app/.deno)

Custom Port

To run on a different port, edit docker-compose.yml:

ports:
    - '8080:8787' # Runs on port 8080 instead

Development Mode

For active development with live reload:

# Source code is already mounted in docker-compose.yml
docker compose up

Changes to files in src/, worker/, and public/ will be reflected automatically.

Example Usage

Using the Web UI

  1. Open http://localhost:8787 in your browser
  2. Switch to "Simple Mode" or "Advanced Mode"
  3. Add filter list URLs or paste a configuration
  4. Click "Compile" and watch the real-time progress
  5. Download or copy the compiled filter list

Using the API

Compile a filter list programmatically:

curl -X POST http://localhost:8787/compile \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "name": "My Filter List",
      "sources": [
        {
          "source": "https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt",
          "transformations": ["RemoveComments", "Deduplicate"]
        }
      ],
      "transformations": ["RemoveEmptyLines"]
    }
  }'

Streaming Compilation SSE

Get real-time progress updates using Server-Sent Events:

curl -N -X POST http://localhost:8787/compile/stream \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "name": "My Filter List",
      "sources": [{"source": "https://example.com/filters.txt"}]
    }
  }'

Troubleshooting

Port already in use

If port 8787 is already in use, stop the conflicting service or change the port in docker-compose.yml before running docker compose up -d.

Container Won't Start

Check the logs:

docker compose logs

Permission Issues

If you encounter permission errors with volumes:

sudo chown -R 1001:1001 ./output

Next Steps

Complete Docker Guide

Advanced configurations, health checks, and Kubernetes examples.

API Documentation

Full REST API reference with schemas and examples.

Configuration Reference

All compiler options and Zod schema reference.

Troubleshooting

Common issues and KB articles for production incidents.

Need help?
Was this page helpful?