lanrenbang/xray-services repository overview

⁠xray-services

English⁠ | 简体中文⁠

Use Xray-core in a secure and simple way. Your configuration files can be shared freely without redaction. With secrets support, even your environment variable configurations can be shared safely.

⁠Features

• Automatic variable substitution in configuration files.
• Support for secrets in environment variables (e.g., Docker/Podman secrets).
• Automatically tracks upstream updates and rebuilds images.
• Provides out-of-the-box server and client configuration templates.
• Includes Docker/Podman build/compose configurations.
• Provides pre-configured Caddy nesting for Compose.
• Includes Systemd service units and automatic geo-data update timers.

⁠Project Structure

.
├── templates                 # Xray configuration templates
│   ├── server                # - Server side
│   └── client                # - Client side
├── log                       # Container volume - Logs
├── v2ray                     # Container volume - Geo data
├── systemd                   # Systemd native execution pack
│   ├── xray.service.d
│   │   └── override.conf     # Drop-in snippet for variable substitution
│   ├── xray.service          # Dynamic user service unit
│   ├── geo-update.timer      # Geo data update timer
│   ├── geo-update.service    # Geo data update service unit
│   └── README.md             # Native execution guide
├── scripts
│   └── geo-update.sh         # Geo data update script
├── .env.warp.example         # Template substitution definitions
├── compose.yaml              # Container orchestration - Sub-service execution
├── compose.override.yaml     # Container override - Standalone execution
├── Dockerfile                # Image generation config
├── README.md
└── README-cn.md

⁠Usage

1. Install Docker or Podman (recommended), or choose to run natively.
2. caddy-services⁠ is recommended as the perfect companion for this project. You can also install other versions of Caddy or Nginx yourself, but you will need to implement the corresponding configurations manually.
3. Clone this repository:

git clone https://github.com/Lanrenbang/xray-services.git

1. Copy or rename .env.warp.example⁠ to .env.warp and modify the necessary content as needed.
2. Refer to the internal comments to modify compose.yaml⁠/compose.override.yaml⁠ as required.
3. Add the information configured as secrets in the previous step to the keystore:

echo -n "some secret" | docker secret create <secret_name> - 
echo -n "some secret" | podman secret create <secret_name> - 

1. Enter the root directory and start the container service:

docker compose up -d
podman compose up -d

⁠Others

• The Server enables the API service interface and traffic statistics by default; configure as needed.
• The Client enables connection observation by default, automatically selecting and using the fastest outbound from 5 available outbounds; configure as needed.
• Both ends strictly support VLESS communication (including raw/xhttp transport). Other requirements can be added manually.
• Both ends enable the new VLESS ML-KEM-768 encryption by default. Generate keys or disable this feature based on your needs.
• The latest REALITY ML-DSA-65 signature mechanism is not used in the configuration. If needed, add the environment variables, secrets, and configuration files yourself.
• If you do not wish to use containers and prefer to run this project natively, please refer to the Native Execution Guide⁠.
• For container health checks, please refer to the HEALTHCHECK Guide⁠.

⁠Related Projects

• caddy-services⁠
• xray-api-bridge⁠

⁠Credits

• Xray-core⁠
• 5-in-1 Configuration⁠

⁠Support Me

⁠License

This project is distributed under the terms of the LICENSE file.