blocky-ui

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #claude-code #cli #windows #codex #developer-tools #dsh

★ 122 Open GitHub ↗

A modern web interface for managing and controlling your Blocky DNS server.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# BlockyUI

BlockyUI is a modern companion dashboard for your [Blocky DNS](https://github.com/0xERR0R/blocky) server. It connects to an existing Blocky instance to display statistics, query DNS records, and much more.

![BlockyUI Screenshot](https://raw.githubusercontent.com/GabeDuarteM/blocky-ui/main/docs/BlockyUI-Screenshot.png)

## ✨ Key Features

- DNS blocking controls with optional timed disable presets
- DNS query tool to test domain blocking and filtering rules
- One-click cache clearing and list refresh
- Search through query logs and filter them (requires [query logging](https://0xerr0r.github.io/blocky/latest/configuration/#query-logging) configured on Blocky)
  - Supports MySQL, PostgreSQL (including Timescale), CSV, CSV-Client, and console (check `QUERY_LOG_CONSOLE_PROVIDER`) logging types from Blocky
  - CSV Query Logging is restricted to the most recent day's logs due to performance considerations
- Statistics sections
  - Overview cards: total queries, blocked requests, cache hit rate, listed domains, average response time (requires [statistics](https://0xerr0r.github.io/blocky/latest/configuration/#statistics) enabled on Blocky)
  - Top domains, blocked domains, and clients use Blocky's rolling 24-hour statistics when query logging is not configured
  - Queries over time and richer top lists with selectable ranges, filtering, and pagination require [query logging](https://0xerr0r.github.io/blocky/latest/configuration/#query-logging) configured on Blocky

## 🏁 Getting Started

### Prerequisites

- A running Blocky server reachable by BlockyUI

### Using Docker Compose

1. Create a `docker-compose.yml` file:

```yaml
services:
  blocky-ui:
    image: ghcr.io/gabeduartem/blocky-ui:latest # or for example `blocky-ui:1.5.0` if you prefer pinned versions
    container_name: blocky-ui
    restart: unless-stopped
    depends_on:
      - blocky

ports:
      - 3000:3000

environment:
      - BLOCKY_API_URL=http://blocky:4000
      # Uncomment to add custom headers to Blocky API requests (e.g. authentication)
      # - BLOCKY_REQUEST_HEADERS={"Authorization":"Bearer your-token-here"}

# Uncomment to enable query logging features

# from a MySQL/MariaDB database:
      # - QUERY_LOG_TYPE=mysql
      # - QUERY_LOG_TARGET=mysql://username:password@localhost:3306/blocky_query_log

# from a PostgreSQL database:
      # - QUERY_LOG_TYPE=postgresql
      # - QUERY_LOG_TARGET=postgresql://username:password@localhost:5432/blocky_query_log

# from a Postgres database with Timescale configured (in postgres AND blocky):
      # - QUERY_LOG_TYPE=timescale
      # - QUERY_LOG_TARGET=postgresql://username:password@localhost:5432/blocky_query_log

# from a SQLite database file:
      # - QUERY_LOG_TYPE=sqlite
      # - QUERY_LOG_TARGET=/path/to/blocky/query-log.db

# from a CSV file (single daily file):
      # - QUERY_LOG_TYPE=csv
      # - QUERY_LOG_TARGET=/path/to/blocky/logs/folder/

# from CSV per-client files (multiple files per day):
      # - QUERY_LOG_TYPE=csv-client
      # - QUERY_LOG_TARGET=/path/to/blocky/logs/folder/

# from VictoriaLogs (blocky queryLog.type: console, logs shipped to VictoriaLogs):
      # - QUERY_LOG_TYPE=console
      # - QUERY_LOG_CONSOLE_PROVIDER=victorialogs
      # - QUERY_LOG_TARGET=http://victoria-logs-host:9428

# Uncomment to display an instance name in the browser tab title
      # Useful when running multiple BlockyUI instances
      # - INSTANCE_NAME=blocky-vm2

blocky:
    image: spx01/blocky
    container_name: blocky
    hostname: blocky
    restart: unless-stopped
    volumes:
      - ./blocky/config.yml:/app/config.yml
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 4000:4000
      - 53:53/udp
```

2. Start the container:

```bash
docker compose up -d
```

Visit `http://localhost:3000` to access BlockyUI.

### Using Docker Run

```bash
docker run -d \
  -p 3000:3000 \
  -e BLOCKY_API_URL=http://your-blocky-server:4000 \
  -e QUERY_LOG_TYPE=mysql \
  -e QUERY_LOG_TARGET="mysql://username:password@localhost:3306/blocky_query_log_table_name" \
  ghcr.io/gabeduartem/blocky-ui:latest
```

## ⚙️ Configuration

BlockyUI is configured via environment variables in all deployment methods.

| Variable                     | Required    | Default                 | Description                                                                                                              |
| ---------------------------- | ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `BLOCKY_API_URL`             | No          | `http://localhost:4000` | Base URL of your Blocky API (usually `http://blocky-host:4000`).                                                         |
| `BLOCKY_REQUEST_HEADERS`     | No          | None                    | JSON object of custom headers for all Blocky API requests (e.g., `'{"Authorization":"Bearer token"}'`).                  |
| `QUERY_LOG_TYPE`             | No          | None                    | Enables query logging. Accepted values: `mysql`, `postgresql`, `timescale`, `sqlite`, `csv`, `csv-client`, or `console`. |
| `QUERY_LOG_CONSOLE_PROVIDER` | Conditional | None                    | Required when `QUERY_LOG_TYPE=console`. Selects the console log backend. Currently supports `victorialogs`.              |
| `QUERY_LOG_TARGET`           | No          | None                    | Connection string, SQLite file path, or log folder path for the same target as Blocky's `queryLog.target`.               |
| `INSTANCE_NAME`              | No          | None                    | Custom label shown in the browser tab title. Useful for identifying multiple instances.                                  |
| `DEMO_MODE`                  | No          | `false`                 | Enables a kiosk mode with mocked data and actions. Useful if you just want to see how it looks.                          |

### Common Setups

- **Basic**: set only `BLOCKY_API_URL`. Server status, operations, and query tools will be visible.
- **Blocky with statistics enabled**: Add [statistics](https://0xerr0r.github.io/blocky/latest/configuration/#statistics) to Blocky's configuration to show the rolling 24-hour overview cards and top lists.
- **Query logging**: Enables query logs and the statistics charts with selectable time ranges, filtering, and pagination.

### Local Development

1. Clone the repository:

```bash
git clone https://github.com/gabeduartem/blocky-ui.git
cd blocky-ui
```

2. Install dependencies:

```bash
bun install
```

3. Configure environment variables:

```bash
cp .env.example .env
# Don't forget to update the file with the correct values
```

4. Start the development server:

```bash
bun dev
```

Visit `http://localhost:3000` to access BlockyUI.

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=gabeduartem/blocky-ui&type=date&legend=top-left)](https://www.star-history.com/#gabeduartem/blocky-ui&type=date&legend=top-left)

## 🤝 Contributing

We welcome contributions! Whether it's bug fixes, new features, or documentation
improvements, your input helps make BlockyUI better. Check out our [Contributing Guide](CONTRIBUTING.md) to get started.

blocky-ui

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README