kutovoys/subs-server repository overview

⁠Subs Server

Subs Server is a lightweight HTTP server for serving base64-encoded subscription files from the local filesystem. It watches files for changes and provides customizable HTTP headers for clients.

⁠✨ Features

• 📁 Serves subscription data from the local filesystem.
• 🔄 Automatically watches for file changes (create, update, delete).
• 🌐 Supports direct protocols (vmess://, vless://, ss://, trojan://, etc.).
• 🌍 Supports remote base64-encoded subscriptions via http(s)://... links.
• ➕ Combines local and remote subscription entries into a single output.
• 🛠 Fully configurable via CLI flags or environment variables.
• 📦 Custom HTTP headers for profile metadata.
• 🐞 Debug mode with listing of all available endpoints.

⁠🚀 Usage

⁠CLI

subs-server \
  --location ./subs \
  --port 2115 \
  --debug

⁠Docker

docker run -d -p 2115:2115 \
  -e LOCATION=/subs \
  -v $(pwd)/subs:/subs \
  kutovoys/subs-server

⁠Docker Compose

services:
  subs-server:
    image: kutovoys/subs-server
    container_name: subs-server
    restart: always
    ports:
      - "2115:2115"
    volumes:
      - ./subs:/subs
    environment:
      LOCATION: /subs
      DEBUG: "true"

⁠⚙️ Configuration

Configuration can be set via CLI flags or environment variables.

⁠🛠 Example

If you place a file test.txt inside the ./subs directory with the content:

vmess://example
https://some-remote-url.com/encoded.txt

and run the server, visiting http://localhost:2115/test will return a single base64-encoded response that includes:

• The vmess://example line.
• All decoded entries fetched from https://some-remote-url.com/encoded.txt.

⁠🤝 Contributing

Contributions to Subs Server are warmly welcomed. Whether it's bug fixes, new features, or documentation improvements, your input helps make this project better. Here's a quick guide to contributing:

1. Fork & Branch: Fork this repository and create a branch for your work.
2. Implement Changes: Work on your feature or fix, keeping code clean and well-documented.
3. Test: Ensure your changes maintain or improve current functionality, adding tests for new features.
4. Commit & PR: Commit your changes with clear messages, then open a pull request detailing your work.
5. Feedback: Be prepared to engage with feedback and further refine your contribution.

Happy contributing! If you're new to this, GitHub's guide on Creating a pull request⁠ is an excellent resource.

⁠VPN Recommendation

For secure and reliable internet access, we recommend BlancVPN⁠. Use promo code TRYBLANCVPN for 15% off your subscription.