Socks5 Proxy Server

Socks5‑proxy‑server is a lightweight, Docker‑centric proxy service that implements the SOCKS v5 protocol with optional authentication and per‑user traffic accounting. The core engine is written in Node.js using the net module for raw TCP handling, while ancillary features such as user management and statistics are exposed through small internal scripts. A dedicated Telegram bot module provides an administrative interface, enabling dynamic user provisioning and real‑time usage monitoring without exposing a web UI.

Key Features

• Authentication & Isolation – Users can be added or removed via CLI scripts (create-user.js, delete-user.js). The server checks credentials against an in‑memory store; when REQUIRE_AUTH=1 anonymous traffic is blocked.
• Traffic Accounting – The users-stats.js script aggregates bytes sent/received per user, allowing administrators to enforce quotas or bill usage.
• Telegram Bot Admin – The bot listens for commands such as /create_user or /users_stats, and can be configured to use webhooks (requiring TLS) or long‑polling.
• Environment‑Driven Configuration – All runtime parameters (APP_PORT, LOG_LEVEL, REQUIRE_AUTH, Telegram tokens, public URL) are injected via a .env file, making the image agnostic to deployment specifics.

Technical Stack

The choice of Node.js allows non‑blocking I/O for high concurrency, while Docker ensures consistent runtime across environments. No external database or ORM is required; user credentials and stats are serialized to disk, simplifying deployment.

Deployment & Infrastructure

The application ships as a single Docker Compose file with two services: proxy and an optional telegram_bot. The proxy listens on a configurable port (APP_PORT, default 54321) and can be exposed behind any reverse‑proxy or firewall. Because the server is stateless apart from local JSON files, it scales horizontally by running multiple instances behind a load balancer; each instance maintains its own user list, so a shared file system or external DB would be needed for true multi‑node consistency.

Containerization is straightforward: docker compose up -d starts both services. The image is minimal (≈70 MB) and requires only the Node runtime, making it suitable for edge devices or cloud VMs. For high‑availability setups, consider mounting the user and stats directories on a shared volume or migrating to an external key‑value store.

Integration & Extensibility

• API Hooks – While the core does not expose a REST API, the internal scripts can be adapted into an Express or Fastify server to provide programmatic user management.
• Webhook Support – The Telegram bot can be extended with custom commands or integrated into CI/CD pipelines.
• Plugin‑Like Architecture – The proxy’s user store is a simple JSON file; swapping it for a Redis or PostgreSQL backend requires minimal code changes.
• Custom Scripts – Developers can add their own Node scripts to the scripts/ folder, leveraging the existing create-user.js pattern for new utilities.

Developer Experience

• Configuration – All settings are environment variables; the .env.example file provides clear documentation.
• CLI Scripts – create-user.js, delete-user.js, and users-stats.js are lightweight, single‑file scripts that can be executed inside the container via docker exec.
• Documentation – The README covers prerequisites, environment variables, CLI usage, and bot configuration.
• Community & Licensing – The project is open‑source under a permissive license (not specified but implied), with active issue tracking and the possibility of community‑driven plugins.

Use Cases

1. Developer Sandbox – Quickly spin up a SOCKS5 proxy for local testing of network‑heavy applications.
2. Edge Routing – Deploy on a home router or VPS to provide authenticated proxy access for IoT devices.
3. Internal Testing – Use the Telegram bot to manage users on‑the‑fly during QA cycles.
4. Educational – Demonstrate proxy protocols and authentication flows in networking courses.

Advantages Over Alternatives

• Zero External Dependencies – No database or message broker needed for core functionality.
• Native Node.js Performance – Asynchronous I/O handles thousands of concurrent TCP connections with low CPU overhead.
• Docker‑First Design – Consistent deployment across cloud providers, VMs, or bare metal.
• Built‑in Admin Bot – Eliminates the need for a separate web dashboard; Telegram’s ubiquity makes it convenient for on‑the‑go management.
• Open Source & Extensible – The simple codebase invites contributors to add features such as ACLs, rate limiting, or integration with OAuth providers.

In summary, socks5‑proxy‑server offers a minimal yet powerful platform for developers who need an authenticated SOCKS v5 proxy that can be managed programmatically or via Telegram, all within a Docker‑friendly footprint.