Senia Web Control

Senia Web Control is a modular, policy-driven web content filtering and classroom network management platform for educational environments. It provides centralized domain blocklist management, real-time incident monitoring, and resilient enforcement on distributed client devices. The system is engineered for scalability, offline operation, and secure, reproducible deployment.

System Overview

Senia Web Control consists of two primary components:

• Server: Central authority for policy management, user authentication, domain blocklists, incident logging, and real-time dashboards. Exposes HTTP and WebSocket APIs and serves the web UI.
• Runner: Lightweight agent installed on client machines. Enforces DNS-based domain blocking, synchronizes with the server, and reports incidents. Designed for resilience, minimal resource usage, and offline operation.

Quick Start

Build All Components (Nix)

make build

Builds both server and runner using Nix for reproducibility. To build only the server or runner:

make build-server
make build-runner

To update Go dependencies for Nix:

make update-gomod2nix

This updates gomod2nix.toml after changing Go dependencies.

Deploy Server (Docker Compose)

docker-compose up -d

This launches the server and MariaDB database using the configuration in docker-compose.yml.

Import or Build Docker Image

Import Prebuilt Image:

docker load -i senia-server.tar
docker-compose up -d

Build Image from Source:

make build-server-mariadb
# or
docker build -f Dockerfile.server -t senia-server:latest .
docker-compose up -d

Install Runner on Clients

Build the Debian package and install on each client:

make build-debian SERVER_URL=http://your-server:8080
sudo SERVER_URL="http://your-server:8080" apt install -y ./webcontrol.deb

Useful Network Scan

nmap -sn 172.20.0.1/16 | grep 'Nmap scan report for' | cut -f 5 -d ' ' | tr '\n' ' '

---

Architecture

High-Level

• Server: Central API, web UI, policy management, incident aggregation, and user authentication.
• Runner: Client-side agent, enforces DNS-based blocking, synchronizes with server, supports offline strategies (keep cache, fail open, strict block).
• Database: MariaDB, stores users, blocklists, incidents, and runner state.
• Deployment: Docker Compose for server/database, Debian package for runner.

Dependency Graph

┌────────────┐       ┌────────────┐       ┌────────────┐
│  Admin UI  │◀───▶│   Server   │◀───▶│  Database  │
└────────────┘       └────────────┘       └────────────┘
	   ▲                   ▲
	   │                   │
	   │                   ▼
   Teachers           Runners (Clients)
	   │                   │
	   ▼                   ▼
   Web UI           DNS Blocking, Incident Reporting

---

Configuration

All configuration is via environment variables:

Variable	Default	Description
SERVER_PORT	8080	HTTP server port
ENVIRONMENT	development	Deployment environment
LOG_LEVEL	info	Logging verbosity
DB_HOST	localhost	Database host
DB_PORT	3306	Database port
DB_USER	root	Database user
DB_PASSWORD	(empty)	Database password
DB_NAME	swc	Database name
SMTP_HOST	localhost	SMTP server host
SMTP_PORT	587	SMTP server port
SMTP_USER	(empty)	SMTP username
SMTP_PASSWORD	(empty)	SMTP password
ALERT_EMAIL	tic@ieslasenia.org	Alert notification email
RUNNER_RATE_LIMIT	1000	Max runner requests per interval
RUNNER_BATCH_SIZE_KB	1048576	Max batch upload size (KB)
TOKEN_SECRET	dev-secret-change-in-prod	JWT signing secret
TEACHER_NETWORK_PREFIX	172.20	Teacher device network prefix
TEACHER_IP_OCTET	80	Teacher device IP octet

Documentation

• docs/server.md: Server component details
• docs/runner.md: Runner component details

Technology Stack

• Go 1.25.5
• MariaDB
• Docker, Docker Compose
• Nix Flakes
• dnsmasq
• systemd
• OpenSSL
• Bulma CSS

License

This project is distributed under the AGPL-3.0 License. Refer to the LICENSE file for details.

    Senia Web Control
    Copyright (C) 2026  Ángel Crujera (me@crujera.net) and contributors

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You may have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.