subconverter-go/docs/deployment.md

Deployment Guide

This guide covers building subconverter-go, producing Docker images, and deploying the service without Kubernetes. It also describes every configuration file parameter so operators can tune behaviour confidently.

1. Prerequisites

• Go 1.22 or later
• GNU Make (optional, for the provided convenience targets)
• A POSIX shell with standard toolchain (git, curl, tar)
• Docker 24+ for container builds
• No external services (Redis, Nginx, databases) are required; the binary is self-contained.

Clone the repository and move into it:

git clone https://github.com/subconverter-go/subconverter-go.git
cd subconverter-go

2. Building From Source

2.1 Fetch Dependencies

The module uses Go modules. The first build pulls dependencies automatically, but you can pre-download them:

go mod download

2.2 Compile the Binary

go build -o build/subconverter ./cmd/cli

The resulting binary reads configuration from config.yaml in the working directory by default. Override the path with --config when launching.

2.3 Run Tests (Recommended)

Use the full suite to catch regressions:

go test ./...

2.4 Install via Makefile (Optional)

A shorthand target is available:

make build

This produces build/subconverter as well.

3. Docker Workflow

3.1 Build the Image

The repository ships with a parameterised Dockerfile. Build and tag an image:

docker build -t subconverter-go:latest .

3.2 Run the Container

Provide a configuration file and optional rule assets via bind mounts or named volumes. The example below mounts the local config.yaml and exposes the HTTP port:

docker run \
  --name subconverter \
  -p 25500:25500 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -v $(pwd)/base:/app/base:ro \
  subconverter-go:latest

Environment variables forwarded into the container override configuration entries when present (see section 4).

3.3 Using docker-compose

For repeatable setups a ready-made docker-compose.yml is included:

docker compose up -d

Edit the compose file to adjust host ports, volume bindings, or environment variables before starting.

4. Configuration Reference

config.yaml controls service behaviour. The configuration loader also honours environment variables using the same keys but upper-cased and prefixed with SUBCONVERTER_ (e.g. SUBCONVERTER_SERVER_PORT).

4.1 server

Key	Type	Description
host	string	Bind address for the HTTP server (0.0.0.0 to serve all interfaces).
port	int	TCP port exposed by the service. Default 25500.
read_timeout	int	Maximum seconds allowed to read a request body before timing out.
write_timeout	int	Maximum seconds allowed to write a response before timing out.
max_request_size	int	Maximum request payload size in bytes. Requests larger than this trigger 413 Payload Too Large.

4.2 logging

Key	Type	Description
level	string	Minimum level to emit (debug, info, warn, error).
format	string	Output format: json for structured logs, text for human-readable lines.
output	string	stdout to log to standard output, or file to log to the path in file.
file	string	Destination file when output is file. Directories are created automatically.
max_size	int	Maximum size in megabytes before the log rotates.
max_age	int	Maximum days to retain old log files.
max_backups	int	Maximum number of rotated log files to keep.
compress	bool	Compress rotated logs with gzip when true.

4.3 security

Key	Type	Description
access_tokens	list[string]	Static bearer tokens. When non-empty all /api and legacy endpoints require token=<value> query parameter or Authorization: Bearer.
cors_origins	list[string]	Allowed Origin headers for CORS preflight requests. Use "*" to allow all.
rate_limit	int	Maximum number of requests per minute per client IP. 0 disables rate limiting.
timeout	int	Request processing timeout in seconds. Requests exceeding this duration return 504.

4.4 conversion

Key	Type	Description
default_target	string	Format used when the client omits target (e.g. clash, surge).
supported_targets	list[string]	Whitelist of allowed output formats. Requests for other formats return 400.
default_emoji	bool	Whether generated node names should include emoji when the client does not specify add_emoji.
default_udp	bool	Enables UDP by default unless the client overrides udp.
max_nodes	int	Maximum number of proxies returned per conversion. 0 means unlimited.
cache_timeout	int	Minutes to cache conversion responses when the cache manager is on.

Additional options parsed from requests (for example upload, rename, ruleset) are stored per request and influence output but are not global configuration keys.

4.5 cache (optional block)

If present it overrides cache manager defaults.

Key	Type	Description
enabled	bool	Toggles the in-memory conversion cache. Defaults to true.
ttl	duration	Expiration window (e.g. 5m, 1h).
maxSize	int	Maximum number of cached entries before evictions occur.
cleanup	duration	Background cleanup interval.

4.6 Environment Overrides

Each configuration entry is mapped to an environment variable by concatenating section and key names. Examples:

• SUBCONVERTER_SERVER_PORT=8080
• SUBCONVERTER_LOGGING_LEVEL=debug
• SUBCONVERTER_CONVERSION_DEFAULT_UDP=true

When both environment variable and YAML entry exist, the environment variable wins.

5. Running the Binary

./build/subconverter --config /path/to/config.yaml

Common overrides:

• --port (short-hand for server.port)
• --host
• --config

Use ./build/subconverter --help to inspect all flags.

6. Deploying on a Single Host (Systemd Example)

1. Copy the compiled binary to /usr/local/bin/subconverter.
2. Copy config.yaml and supporting assets (e.g. base/) to /etc/subconverter/.
3. Create /etc/systemd/system/subconverter.service:

[Unit]
Description=SubConverter-Go
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/subconverter --config /etc/subconverter/config.yaml
Restart=on-failure
User=subconverter
Group=subconverter
WorkingDirectory=/etc/subconverter
Environment=SUBCONVERTER_LOGGING_OUTPUT=stdout

[Install]
WantedBy=multi-user.target

4. Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now subconverter

Monitor logs with journalctl -u subconverter -f.

7. Updating

• For binary deployments: stop the service, replace the binary, restart.
• For Docker deployments: rebuild the image (docker build) and recreate the container (docker compose up -d --build).

Always re-run go test ./... after upgrading dependencies or modifying conversion logic.

8. Troubleshooting Checklist

• Startup fails: ensure the configured port is free and the base/ directory is mounted (contains default templates and rule sets).
• 403 responses: populate security.access_tokens and pass token query parameter (or clear the list to disable auth).
• Slow conversions: consider increasing server.write_timeout and enabling cache (cache.enabled: true).
• Large payloads rejected: raise server.max_request_size.

For additional compatibility notes see docs/compatibility.md.