remotecellist/wireguard-acl repository overview

⁠WireGuard ACL Web UI

A unified Dockerized solution to manage WireGuard VPN access control lists (ACLs) via a web UI with built-in monitoring and failsafe host lockdown capabilities. The container runs both the web UI and monitor in a single instance for simplified deployment.

Features:

• Web UI for managing user access rules
• Automatic ACL script deployment to WireGuard container
• Built-in monitoring with host lockdown failsafe
• Checksum-based script updates (only updates when changed)
• Host network access for iptables management

Note: WireGuard defaults are based on Linuxserver/wireguard. If using a different WireGuard container, adjust names and directories using environment variables.

⁠Image

docker pull remotecellist/wireguard-acl:latest

⁠Quick start (docker run)

Create a strong flask key:

openssl rand -base64 32 # generate a strong secret key

Run the unified container (web UI + monitor):

docker run -d \
  --name wireguard-acl \
  --privileged \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add SYS_ADMIN \
  -e APP_PASSWORD='change-me' \
  -e FLASK_SECRET_KEY='paste-generated-key' \
  -e ENABLE_HOST_LOCKDOWN=true \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /lib/modules:/lib/modules:ro \
  -v ./users-data:/app/users-data:rw \
  --restart unless-stopped \
  remotecellist/wireguard-acl:latest

Access the web UI at: http://localhost:5001

If your WireGuard container name, config dir, or port differ from defaults, add:

-e DOCKER_WIREGUARD_CONTAINER_NAME=my-wg \
-e WIREGUARD_CONFIG_DIR=/etc/wireguard \
-e WIREGUARD_PORT=51820 \

⁠Quick start (docker compose)

Create a strong flask key:

openssl rand -base64 32 # generate a strong secret key

Use the compose below in your desired directory:

services:
  wireguard-acl:
    image: remotecellist/wireguard-acl:latest
    container_name: wireguard-acl
    restart: unless-stopped
    privileged: true
    network_mode: host
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
    environment:
      - FLASK_SECRET_KEY=your-secret-key-here
      - APP_PASSWORD=your-app-password-here
      - WEB_PORT=5001
      - DOCKER_WIREGUARD_CONTAINER_NAME=wireguard
      - ENABLE_HOST_LOCKDOWN=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /lib/modules:/lib/modules:ro
      - ./users-data:/app/users-data:rw
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:5001/api/check_session"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

Access the web UI at: http://localhost:5001

Notes:

• A separate WireGuard container must already be running (defaults assume it is named wireguard with configs in /config)
• The container uses host networking for iptables access - no port mapping needed
• If your WireGuard container name or ports differ from the defaults, set:
  • DOCKER_WIREGUARD_CONTAINER_NAME (default: wireguard)
  • WIREGUARD_CONFIG_DIR (default: /config)
  • WIREGUARD_PORT (default: 51820, used for lockdown)

⁠Environment variables

Required:

• FLASK_SECRET_KEY: Flask session secret. Generate one: openssl rand -base64 32
• APP_PASSWORD: UI login password

Optional:

• WEB_PORT: Port the UI binds to inside the container (default: 5001)
• DOCKER_WIREGUARD_CONTAINER_NAME: Name of the running WireGuard container (default: wireguard)
• WIREGUARD_CONFIG_DIR: Directory inside the WireGuard container containing configs (default: /config)
• WIREGUARD_PORT: UDP port used by WireGuard on the host (default: 51820)
• ENABLE_HOST_LOCKDOWN: Enable host lockdown if WireGuard fails (default: true)
• USERS_DATA_DIR: Directory holding users data (default: /app/users-data)
• USERS_FILE: Users JSON filename (default: users.json)
• SESSION_LIFETIME_HOURS: Flask session lifetime in hours (default: 24)
• LOG_LEVEL: Python logging level (default: INFO)

⁠Volumes

• /app/users-data (rw): Persists users configuration (users.json)
• /var/run/docker.sock (ro): Enables the UI to execute docker commands against your WireGuard container
• /lib/modules (ro): Required for iptables functionality

⁠Ports

• Host networking: The container uses network_mode: host, so the web UI is accessible directly on localhost:5001
• No port mapping needed: With host networking, no -p flags or ports: section required

⁠Health check

• The UI exposes GET /api/check_session which returns { "isAuthenticated": <bool> }.

⁠Requirements

• A running WireGuard container with configs under ${WIREGUARD_CONFIG_DIR} (default: /config)
• Docker Engine socket mounted read-only at /var/run/docker.sock
• Host networking access for iptables management
• Privileged container mode for host lockdown functionality

⁠Security notes

• Always set strong values for APP_PASSWORD and FLASK_SECRET_KEY
• The container runs with privileged: true and network_mode: host for iptables access
• Limit access to the UI port via your firewall/reverse proxy
• The Docker socket grants control over the Docker host - keep it read-only
• Host lockdown will block WireGuard traffic if the container fails repeatedly

⁠Troubleshooting

• Lockdown not working: Ensure the container has privileged: true and network_mode: host
• Script not updating: The container uses checksum comparison - only updates when the script changes
• Access issues: With host networking, access via localhost:5001 instead of container name