Deployment

xrat can be deployed in various configurations, from single-user desktop setups to multi-user server deployments with PostgreSQL.

Deployment Options

Option	Description	Use Case
systemd	Run as a systemd user service	Persistent daemon, auto-start on boot
Database Backends	SQLite vs PostgreSQL	Single-user vs multi-user deployments

Quick Deployment Checklist

Build xrat: cargo build --release
Install binary: Copy target/release/xrat to /usr/local/bin/
Create config directory: mkdir -p ~/.config/xrat
Write config.toml: Configure database, runtime, testing settings
Import subscriptions: xrat import https://example.com/sub.txt
Test configs: xrat test --enabled-only
Start daemon: xrat daemon start or use systemd
Enable rotation (optional): xrat proxy start
Start HTTP API (optional): xrat serve or enable in daemon

Environment Variables

xrat respects these environment variables:

Variable	Description
`XRAT_PATH`	Config directory path (default: `~/.config/xrat`)
`RUST_LOG`	Log level (overrides `--verbose`/`--quiet`)
`XRAT_API_KEY`	HTTP API authentication key
`XRAT_SOCKS_PASSWORD`	SOCKS inbound password
`XRAT_SHADOWSOCKS_PASSWORD`	Shadowsocks inbound password
`XRAT_POSTGRES_USER`	PostgreSQL username
`XRAT_POSTGRES_PASSWORD`	PostgreSQL password

Binary Dependencies

xrat requires external proxy binaries:

Binary	Required For	Installation
`xray`	Managed runtime, most parse/test/generate flows	Xray-core releases
`v2ray`	Alternative managed runtime binary	V2Ray releases
`sing-box`	Parse-time sing-box JSON preview and Hysteria2 diagnostics only	sing-box releases

Ensure binaries are in PATH or specify paths in config.toml:

[paths]
xray = "/usr/local/bin/xray"
v2ray = "/usr/local/bin/v2ray"
sing_box = "/usr/local/bin/sing-box"

Managed runtime process lifecycle is Xray/V2Ray-focused. sing-box is not yet a managed runtime replacement for xrat connect.

Security Considerations

File Permissions

Restrict access to config directory:

chmod 700 ~/.config/xrat
chmod 600 ~/.config/xrat/config.toml
chmod 600 ~/.config/xrat/db.sqlite

Network Exposure

By default, xrat binds to:

SOCKS5: 0.0.0.0:1080 (all interfaces)
HTTP API: 127.0.0.1:8080 (localhost only)

To restrict SOCKS5 to localhost:

[runtime.socks]
host = "127.0.0.1"

To expose HTTP API externally (with authentication):

[server]
host = "0.0.0.0"
port = 8080
key = { env = "XRAT_API_KEY" }

Secrets Management

Use environment variables for sensitive values:

[server]
key = { env = "XRAT_API_KEY" }

[runtime.socks]
auth = { enabled = true, username = "xrat", password = { env = "XRAT_SOCKS_PASSWORD" } }

Set in shell profile or systemd service:

export XRAT_API_KEY=$(openssl rand -hex 32)
export XRAT_SOCKS_PASSWORD=$(openssl rand -hex 16)

Monitoring

Health Checks

Use the HTTP API for monitoring:

curl http://localhost:8080/health

Logs

View daemon logs:

journalctl --user -u xrat-daemon -f

Or with direct execution:

RUST_LOG=info xrat daemon start 2> daemon.log

Process Monitoring

Check if daemon is running:

xrat daemon status
ps aux | grep xrat

Backup and Recovery

SQLite

Backup the database file:

cp ~/.config/xrat/db.sqlite ~/backup/db.sqlite.$(date +%Y%m%d)

PostgreSQL

Use pg_dump:

pg_dump xrat > ~/backup/xrat.$(date +%Y%m%d).sql

Config Files

Backup config directory:

tar czf ~/backup/xrat-config.$(date +%Y%m%d).tar.gz ~/.config/xrat/

Troubleshooting

Daemon Won’t Start

Check:

Is a daemon already running? xrat daemon status
Check logs: RUST_LOG=debug xrat daemon start
Verify socket directory is writable

Connection Failed

Check:

Is Xray binary available? which xray
Test config manually: xrat test <id>
Check runtime logs: ~/.config/xrat/runtime/session-*.err.log

Database Locked (SQLite)

Symptom: “database is locked” errors

Fix:

Only one process can write to SQLite at a time
Use PostgreSQL for multi-user deployments
Increase busy timeout in config.toml (if supported)

systemd — systemd service examples
Database Backends — SQLite vs PostgreSQL
Configuration — config.toml reference

Keyboard shortcuts