bilxio/v2ray repository overview

⁠V2Ray v4.x Docker Image (Alpine-based, Secure Non-root)

A lightweight and secure Docker image for V2Ray v4 (specifically version v4.45.2, the final stable release of the 4.x branch). This image is built with security and minimalism in mind, utilizing a multi-stage Alpine build to minimize the container's attack surface.

⁠🚀 Key Features

• 🔒 Non-root Security: The container process runs as an unprivileged system user v2ray (UID/GID configured) rather than root, greatly reducing container breakout risks.
• ⚡ Extremely Lightweight: Based on Alpine Linux, keeping the final image size under 30MB.
• ⚙️ Legacy v4.x CLI & Binaries: Bundles both v2ray and the necessary v2ctl helper utility. Fully configured to use the classic -config parameter syntax.
• 🛡️ Immutable Assets: Pre-packaged with standard geoip.dat and geosite.dat routing assets in /usr/local/share/v2ray/.

⁠🛠️ Quick Start

⁠1. Prepare your Configuration File

Create a configuration directory and save your config.json file.

Example path: /etc/v2ray/config.json

A minimal VLESS configuration template (config.json):

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "port": 10086,
      "protocol": "vless",
      "settings": {
        "clients": [
          {
            "id": "b831381d-6324-4d53-ad4f-8cda48b32611"
          }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp"
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

⁠2. Run with Docker CLI

For proxy tools, Host Network Mode (--network host) is highly recommended to bypass Docker's user-land proxy network translation, reducing CPU overhead and latency.

docker run -d \
  --name v2ray-v4 \
  --restart always \
  --network host \
  -v /etc/v2ray/config.json:/etc/v2ray/config.json:ro \
  yourusername/v2ray:4.45.2-alpine

Note: Replace yourusername/v2ray:4.45.2-alpine with your actual pushed Docker Hub image tag.

⁠3. Run with Docker Compose

If you prefer docker-compose, create a docker-compose.yml file in your working directory:

services:
  v2ray:
    image: yourusername/v2ray:4.45.2-alpine
    container_name: v2ray-v4
    restart: always
    network_mode: "host" # Bypasses bridge translation to optimize speed & throughput
    volumes:
      - ./config.json:/etc/v2ray/config.json:ro # Mount as Read-Only for safety
    command: ["-config", "/etc/v2ray/config.json"]

Run the container using:

docker compose up -d

⁠📂 Directory Layout inside Container

• /usr/local/bin/v2ray - Main executable
• /usr/local/bin/v2ctl - v4.x configuration control utility
• /usr/local/share/v2ray/ - Routing databases (geoip.dat, geosite.dat)
• /etc/v2ray/config.json - Default configuration file path (to be mounted)

⁠🔒 Security Best Practices

1. Read-Only Mount: Always mount your config.json with :ro (Read-Only) flag to prevent the containerized process from modifying its own setup if compromised.
2. Low Port Binding: If you wish to bind to privileged ports below 1024 (like 80 or 443) on a bridge network, map them externally (e.g. -p 80:10086) instead of running the container process as root.