Quick Start

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/jaypatrick/bloqr-compiler.git
cd bloqr-compiler

Start with Docker Compose
Terminal window
```
docker compose up -d
```
Access the application

Surface URL
Web UI http://localhost:8787
API Documentation http://localhost:8787/api
Test Interface http://localhost:8787/test.html
Metrics http://localhost:8787/metrics

Surface	URL
Web UI	http://localhost:8787
API Documentation	http://localhost:8787/api
Test Interface	http://localhost:8787/test.html
Metrics	http://localhost:8787/metrics

Managing the Container

View logs
Terminal window
```
docker compose logs -f
```
Stop the container
Terminal window
```
docker compose down
```
Restart the container
Terminal window
```
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.

Quick Start

Clone and enter the repository

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

Run the development task
Terminal window
```
deno task dev
```
Open local endpoints

Surface URL
Web UI http://localhost:8787
API Documentation http://localhost:8787/api
Metrics http://localhost:8787/metrics

Surface	URL
Web UI	http://localhost:8787
API Documentation	http://localhost:8787/api
Metrics	http://localhost:8787/metrics

Quick Start

Run the Worker locally
Terminal window
```
deno task wrangler:dev
```

Compile against local Worker endpoints

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

Deploy to Cloudflare
Terminal window
```
deno task wrangler:deploy
```

Example Usage

Using the Web UI

Open http://localhost:8787 in your browser
Switch to “Simple Mode” or “Advanced Mode”
Add filter list URLs or paste a configuration
Click “Compile” and watch the real-time progress
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

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.