How ngoduykhanh/wireguard-ui works
Project Type and Purpose
• Project Type: It’s a full-stack web application (backed by a Go server) designed specifically for managing WireGuard configurations and client details.
• Purpose: Offering a friendly web UI that facilitates VPN client management, configuration distribution (via QR code, file, email, Telegram), and server settings customization.
File Structure
• Top-level Organization:
• Main Go server entry: main.go initializes the server.
• Directories such as “handler” (HTTP request handlers, routes, and session management), “router” (defining routing and validation), “model” (data models representing clients, servers, settings, etc.), “store” (data persistence using JSON-based storage), “emailer” (handling different email delivery methods), and “telegram” (Telegram bot integration).
• “templates” holds HTML templates for the web UI.
• “custom” and “assets” contain static assets like JS, images, and possibly CSS.
• “db” might represent the database configuration (or marker) and related ignore settings.
• “util” provides helper functions and configuration utilities.
• Supporting Files:
• Dockerfile, docker-compose.yaml, and example docker-compose setups highlight container deployment.
• Configuration and environment variable details in the README guide runtime behavior.
• Build scripts like “prepare_assets.sh” and continuous integration files under “.github” directory.
Architectural Insights from the README
• The README emphasizes managing WireGuard configuration, including handling logins, serving client configurations, and managing environment-related settings.
• It explains how to run the service both as a binary and within Docker using docker-compose.
• There are integration points for restarting the WireGuard daemon (via systemd or openrc) suggesting an operational flow outside of the core application for infrastructure management.
a. Main Components to Include:
• Client Browser / Frontend: Represents the user interface that interacts with the application.
• Web Server / Backend: A monolithic Go server that handles requests. Within this, illustrate submodules:
• Router & Handlers: Where routes, middlewares, and session management are defined.
• Business Logic and Models: Represented by the “model” package which structures client, server, and configuration data.
• Data Store: The persistence layer implemented in the “store” package (with the JSONDB module).
• Template Engine: Utilizes the “templates” folder to render dynamic HTML views.
• Static Assets: “assets” and “custom” directories for CSS, JavaScript, and images.
• External Services & Integrations:
• Email Service: The “emailer” module which supports SendGrid and SMTP for sending emails.
• Telegram Integration: The “telegram” module for optionally delivering config via Telegram.
• WireGuard Service: Although not managed directly by the application, the system interacts with the WireGuard configuration (as directed by generated configs and potential service restarts).
b. Relationships and Data Flow:
• User actions in the browser send HTTP requests to the Go server.
• The router dispatches these requests to the appropriate handlers.
• Handlers interact with the model and store to perform CRUD operations on client and server data.
• Depending on actions (e.g., “send config by email”), the system utilizes the emailer or telegram modules.
• The server generates or updates configuration files (using templates and util functions) which could then trigger external operations (like restarting WireGuard via Docker or systemd).
c. Architectural Patterns and Principles:
• MVC/Modular Structure: Although consolidated into a single service, the separation between routing, handling, and data persistence shows a clear modular approach.
• Configuration through Environment Variables: Emphasize how behavior is controlled via environment settings.
• Containerization: The Dockerfile and docker-compose setups illustrate deployment best practices.
d. Key Technologies & Frameworks:
• Go for the backend implementation.
• Docker for containerized deployments.
• SMTP and SendGrid for email delivery.
• Telegram Bot API for messaging.
• Standard HTML templating for the frontend.