This guide explains how to run v2rayA with Docker and Docker Compose. v2rayA provides a user-friendly web UI for managing and configuring a V2Ray client in a scalable, maintainable container environment.

1. Preparation

1.1 Docker Installation

Install Docker:

sudo pacman -S docker

Add your user to the Docker group:

sudo usermod -aG docker $(whoami)

Create the Docker configuration directory:

sudo mkdir -p /etc/docker

Create /etc/docker/daemon.json to use a registry mirror:

cat <<EOF | sudo tee /etc/docker/daemon.json > /dev/null
{
    "registry-mirrors": [
        "https://dockerproxy.net"
    ]
}
EOF

Enable and start Docker:

sudo systemctl daemon-reload
sudo systemctl enable --now docker

Verify Docker:

docker ps

Tip: Adding your user to the Docker group avoids having to use sudo for every Docker command. Tip: Use registry mirrors to speed up image downloads.

1.2 Docker Compose Installation

Install Docker Compose:

sudo pacman -S docker-compose

Verify installation:

docker-compose --version

Tip: Docker Compose helps manage multi-container applications easily.

2. v2rayA Setup

2.1 Project Directory

Create project directories:

mkdir -p software/v2raya/data

Create the Docker Compose file:

nvim software/v2raya/docker-compose.yml

2.2 Docker Compose Configuration

Example docker-compose.yml:

services:
  v2raya:
    image: mzz2017/v2raya:v2.2.5.8
    restart: always
    privileged: true
    network_mode: host
    container_name: v2raya
    environment:
      V2RAYA_LOG_FILE: /tmp/v2raya.log
      V2RAYA_V2RAY_BIN: /usr/local/bin/xray
      V2RAYA_NFTABLES_SUPPORT: off
      IPTABLES_MODE: legacy
    volumes:
      - /lib/modules:/lib/modules:ro
      - /etc/resolv.conf:/etc/resolv.conf
      - $PWD/data:/etc/v2raya
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

2.3 Container Startup

cd software/v2raya
docker-compose up -d

Check the container status:

docker ps | grep v2raya

Tip: Make sure the $PWD/data path matches your Docker Compose setup. Tip: Use docker logs v2raya to check container status if issues occur.

3. Web UI Configuration

Open the v2rayA web UI:

  • Open http://localhost:2017 in your browser.

3.1 Proxy Settings

  • Go to Settings → GFWList
  • Change from off to on (Proxy only GFWList)

Tip: This ensures only traffic to blocked sites is proxied.

3.2 VLESS Node Configuration

To add a VLESS node for your V2Ray server:

  1. Click Create → VLESS
  2. Enter the details from your V2Ray server:
    • Address: yourdomain.com
    • Port: 443
    • UUID: your_uuid (generated in server setup)
    • Encryption: environment
    • Transport: WebSocket
    • WebSocket Path: /ws/8f3a7b2c9d (as configured on server)
    • TLS: Enabled
    • SNI / Host: yourdomain.com
  3. Save the node.
  4. Test the node in v2rayA to confirm that it connects successfully.

Tip: Use a randomized WebSocket path for security and stealth. Tip: Always verify UUID and path match exactly with the server configuration.

3.3 Firefox Proxy Example

  • HTTP Proxy: 127.0.0.1:20171
  • SOCKS5 Proxy: 127.0.0.1:20170

Tip: Make sure the browser is using the correct proxy to route traffic through v2rayA.

4. Security

  • Use a strong password, and secure the Docker socket if you expose it remotely.
  • Keep Docker and v2rayA up to date:
sudo pacman -Syu
  • Limit container privileges if not using privileged: true.
  • Regularly back up your v2rayA data directory.

5. Backup and Restore

5.1 Configuration Backup

sudo mkdir -p /root/backup/v2raya
sudo cp -r software/v2raya/data /root/backup/v2raya/data.bak

5.2 Configuration Restore

sudo rm -rf software/v2raya/data
sudo cp -r /root/backup/v2raya/data.bak software/v2raya/data
docker-compose restart

Tip: Always stop containers before restoring backup. Tip: Keep multiple backup versions for safety.

6. Troubleshooting

6.1 Container Startup Errors

Check container logs:

docker logs v2raya

Common causes:

  • Incorrect volume paths
  • Docker network issues
  • An incomplete image pull

6.2 Docker Compose Issues

Check Docker Compose syntax:

docker-compose config

Fix errors and restart:

docker-compose down
docker-compose up -d

6.3 Web UI Access Errors

  • Ensure the container is running (docker ps).
  • Verify localhost:2017 is accessible.
  • Confirm that the nodes are correctly configured in the web UI.
  • Check browser proxy settings (HTTP: 20171, SOCKS5: 20170).

Tip: Use docker logs v2raya to debug any connection issues in real time.