Installation & Deployment Operations
Relevant source files
The following files were used as context for generating this wiki page:
Installation and deployment operations manage the lifecycle of the HX-ProxyGroup system, including initial setup, version upgrades, and disaster recovery. The system utilizes a bash-driven installer that targets Linux environments with systemd to maintain three distinct services: a control plane, a data plane (Mihomo), and a terminal helper.
These operations ensure secure execution by using an unprivileged service account, verifying release integrity via SHA-256 checksums, and providing automatic rollbacks if a new version fails readiness checks. Deployment extends beyond the local server to include Cloudflare Workers for residential proxy tunneling.
Sources: install.sh:4-45, SECURITY.md:12-28, internal/cfworker/deploy.go:100-110
System Architecture & Components
The installation process deploys three primary systemd units and establishes a specific directory structure for configuration and persistent data.
Systemd Services
| Service Name | Purpose | Privileges |
|---|---|---|
hx-proxygroup.service | Management API and control plane logic. | Unprivileged (NoNewPrivileges=true) |
hx-proxygroup-dataplane.service | Independent Mihomo proxy kernel. | Unprivileged |
hx-proxygroup-terminal.service | Root PTY helper for browser terminal. | Root (Validated via SO_PEERCRED) |
Sources: install.sh:4-8, install_test.go:21-70, SECURITY.md:29-45
Directory Structure
The installer organizes files to separate static binaries from mutable state:
/usr/local/lib/hx-proxygroup: Contains versioned releases and acurrentsymlink to the active version./etc/hx-proxygroup: Storesconfig.yamland sensitive master keys./var/lib/hx-proxygroup: Holds the SQLite database, snapshots, and runtime configuration (active.yaml)./var/log/hx-proxygroup: Dedicated logs for the service account.
Sources: install.sh:10-15, install.sh:110-120, install_test.go:21-30
Installation Workflow
The install.sh script executes a multi-stage process to ensure the environment is ready before switching active versions.
The diagram shows the sequence of checks and actions performed during a standard installation or upgrade.
Sources: install.sh:90-105, install.sh:195-235, install.sh:245-255
Release Integrity Verification
Release bundles are compressed .tar.gz archives. The installer verifies the SHA256SUMS file against the downloaded bundle before extraction. It also performs an "unsafe path" check to prevent directory traversal attacks during extraction.
Sources: install.sh:152-170, install_test.go:105-115
Deployment Operations
Version Upgrades
Users initiate upgrades via sudo hx-proxygroup-install upgrade. The system fetches the latest release tag from GitHub or uses a provided offline directory. Upgrades follow an atomic pattern:
- Download and extract the new version to a unique subdirectory.
- Save current systemd units as backups.
- Update the
currentsymlink. - Restart services and wait up to 45 seconds for a healthy status from the API.
Sources: install.sh:25-35, install.sh:210-230, web/src/pages/about-page.tsx:50-70
Cloudflare Worker Deployment
The system automates the deployment of residential tunnels to Cloudflare Workers.
- Neutral Naming: It generates business-neutral names (e.g.,
aurora10) to avoid proxy-related keywords. - Obfuscation: A specialized
obfuscate.shscript processes theworker.jstemplate to generate a randomized recipe for each deployment. - Environment Variables: Tunnels are configured with random UUIDs and 12-character hex paths.
Sources: internal/cfworker/deploy.go:37-45, internal/cfworker/deploy.go:100-140, scripts/package-release.sh:58-65
Backup and Recovery
The system provides two types of data preservation: Disaster Backups and Artifacts.
Disaster Backups
Created via install.sh backup, these are root-owned tar.gz files containing the entire /etc and /var/lib directories. These backups include secrets (master keys and database files) and are intended for full instance restoration.
Sources: install.sh:285-300, SECURITY.md:12-20
Application Artifacts
Managed through the UI, these provide more granular control:
- Backups: SQLite Online Backup snapshots containing consistent database copies.
- Portable Exports: Non-sensitive state excluding keys, credentials, and runtime configs.
Sources: web/src/pages/artifacts-page.tsx:40-65, web/src/pages/artifacts-page.tsx:85-95
Security Operations
Terminal Security
The hx-proxygroup-terminal.service runs as root to create a PTY, but it only communicates via a Unix socket (/run/hx-proxygroup/terminal.sock) protected by group permissions. It validates the peer using SO_PEERCRED to ensure only the control plane can request a terminal session.
Sources: install_test.go:42-55, SECURITY.md:46-65
Operational Security Commands
| Command | Action |
|---|---|
hx-proxygroup-install repair | Re-installs systemd units and verifies binary integrity. |
hx-proxygroup-install uninstall | Removes binaries and services but preserves data/config. |
hx-proxygroup-install purge | Deletes all files, including data, and removes the service account. |
Sources: install.sh:265-280, install.sh:315-330
Conclusion
Installation and deployment operations prioritize system stability through atomic updates and health-checked rollbacks. The separation of concerns between the unprivileged control/data planes and the privileged terminal helper ensures that the system maintains a high security posture while allowing for automated lifecycle management.