Modern deployment, orchestration, and disaster recovery suite for PasarGuard Panel and Nodes.
English • راهنمای فارسی (Standalone) • راهنمای فارسی نود (Standalone)
- Overview
- Architecture
- System Requirements & OS Support
- Quick Start
- Installation Options
- Master CLI Reference
- Database Support Matrix
- Backups & Disaster Recovery
- SSL & TLS Security
- Domestic Mirrors & Air-Gapped Networks
- Documentation Index
- Contributing & Testing
PasarGuard Scripts provides battle-tested automation for deploying and maintaining production-grade PasarGuard infrastructure:
- PasarGuard Panel (
pasarguard.sh/pasarguard): Orchestrates the web dashboard, database engines (SQLite, MySQL, MariaDB, PostgreSQL, TimescaleDB), PgBouncer connection pooling, admin web UIs (pgAdmin, phpMyAdmin), and disaster recovery. - PasarGuard Node (
pg-node.sh/pg-node): Manages remote worker nodes, systemd background daemons (pg-node-service), Xray-core versions, routing geofiles, and TLS certificates. - Disaster Recovery: Automated recurring backups to Telegram with proxy support, multi-database cluster snapshots, and fail-closed TimescaleDB version compatibility gates.
- Domestic Mirror Optimization: Benchmark and apply domestic Iranian mirrors for APT and Docker when deploying behind restricted network environments.
┌─────────────────────────────────────────┐
│ PasarGuard Panel │
│ (Web Dashboard & Background Tasks) │
└──────┬──────────────────────┬───────────┘
│ │
┌──────────────────┴────────┐ ┌──────┴────────────────────┐
▼ ▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐ ┌───────────────────┐
│ SQLite / MySQL │ │ PgBouncer │ │ Automated Backup │
│ / MariaDB │ │ (Port 6432 Pool) │ │ (Telegram + Cron)│
└─────────────────┘ └────────┬───────────┘ └───────────────────┘
│
┌────────┴───────────┐
│ PostgreSQL 17 / │
│ TimescaleDB │
└────────────────────┘
▲
│ (Encrypted gRPC / REST)
┌───────────────────────────┴───────────────────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Worker Node: EU-1 │ │ Worker Node: AS-1 │
│ (pg-node + Xray) │ │ (pg-node + Xray) │
└─────────────────────┘ └─────────────────────┘
| Operating System | Package Manager | Status |
|---|---|---|
| Ubuntu 20.04 / 22.04 / 24.04 | apt-get |
Supported (Primary) |
| Debian 11 / 12 | apt-get |
Supported |
| CentOS / RHEL 8+ | dnf / yum |
Supported |
| Rocky Linux / AlmaLinux 8+ | dnf |
Supported |
| Fedora 38+ | dnf |
Supported |
| Arch Linux | pacman |
Supported |
| openSUSE Leap / Tumbleweed | zypper |
Supported |
Prerequisites:
- Linux x86_64 or ARM64
- Root or
sudoprivileges - Docker and Docker Compose (automatically installed if absent)
curl,tar,gzip
Download and inspect the installer on your server (or pin to an immutable release tag):
# Download installer script
curl -fsSL https://raw.githubusercontent.com/PasarGuard/scripts/main/pasarguard.sh -o pasarguard.sh
# Default install (SQLite, interactive SSL)
sudo bash pasarguard.sh install
# High-concurrency production install (TimescaleDB + PgBouncer)
sudo bash pasarguard.sh install --database timescaledb --pre-release(Tip: In production environments, review the script or pin to a specific release tag, e.g. https://raw.githubusercontent.com/PasarGuard/scripts/<tag>/pasarguard.sh).
Once installed, control the panel at any time using the global pasarguard command:
sudo pasarguard statusOn each remote worker node, download and execute the node installer:
# Download node installer script
curl -fsSL https://raw.githubusercontent.com/PasarGuard/scripts/main/pg-node.sh -o pg-node.sh
# Standard node installation
sudo bash pg-node.sh install
# Multi-instance node with custom name
sudo bash pg-node.sh install --name node-de1 --self-signedOnce installed, manage the node using the global pg-node command:
sudo pg-node statusThe following flags can be supplied to pasarguard install:
| Option | Values | Description |
|---|---|---|
--database |
sqlite, mysql, mariadb, postgresql, timescaledb |
Database backend engine. Default is sqlite. (PostgreSQL and TimescaleDB require v1.0.0+) |
--version <TAG> |
e.g. v0.5.2, v1.0.0-beta.1 |
Pin the installation to an explicit release version tag. |
--dev |
(flag) | Install latest development image (v0.x releases only). |
--pre-release |
(flag) | Install latest pre-release image (v1.0.0 and later). |
--ssl |
(flag) | Launch interactive SSL certificate configuration wizard during setup. |
--no-ssl |
(flag) | Skip SSL setup (panel binds to localhost for reverse proxy fronting). |
--ssl-domain <DOMAIN> |
e.g. panel.example.com |
Automatically issue a Let's Encrypt SSL certificate for the domain. |
--ssl-http-port <PORT> |
e.g. 80 |
Port used to verify ACME HTTP-01 challenge. Default: 80. |
| Command | Description |
|---|---|
pasarguard install |
Full panel setup wizard with database and SSL selection. |
pasarguard install-script |
Installs global pasarguard CLI command and shared libraries to system. |
pasarguard install-node |
Shortcut to download and launch the node installer. |
pasarguard up |
Starts all containers in the stack (docker compose up -d). |
pasarguard down |
Stops and tears down stack containers. |
pasarguard restart |
Restarts all containers and prompts to tail logs. |
pasarguard status |
Real-time container health, port mappings, and database status. |
pasarguard logs |
Live log streaming for all stack containers. |
pasarguard cli |
Launches interactive CLI session inside the panel container. |
pasarguard tui |
Opens curses-based Terminal User Interface (TUI). |
pasarguard backup |
Immediate manual backup of database, configuration, and state. |
pasarguard backup-service |
Configures automated recurring Telegram backups and cron schedule. |
pasarguard restore |
Restores panel state and database with pre-restore validation and version compatibility gates. |
pasarguard update |
Pulls latest Docker images and recreates containers cleanly. |
pasarguard uninstall |
Removes containers, services, and optional application data directories. |
pasarguard edit |
Opens /opt/pasarguard/docker-compose.yml in default editor. |
pasarguard edit-env |
Opens /opt/pasarguard/.env in default editor. |
pasarguard completion |
Installs Bash/Zsh tab-completion scripts. |
pasarguard version-script |
Shows current script version and active Git commit SHA. |
pasarguard help |
Displays quick reference help banner. |
👉 For an exhaustive breakdown of panel commands and options, see docs/cli-reference.md.
| Command | Description |
|---|---|
pg-node install |
Installs or reinstalls the worker node container and service. |
pg-node up / down / restart |
Controls the node container stack lifecycle. |
pg-node status |
Displays IP, active service port, certificate path, and Xray version. |
pg-node logs |
Streams live logs from the node container. |
pg-node core-update |
Updates or switches the installed Xray-core binary version. |
pg-node geofiles |
Downloads official geoip.dat and geosite.dat routing assets. |
pg-node renew-cert |
Regenerates self-signed TLS certificates with SAN entries. |
pg-node service-install |
Registers and enables the companion systemd service daemon. |
pg-node service-status |
Inspects systemd service status (pg-node-service.service). |
pg-node service-logs |
Tails journalctl logs for the background service. |
pg-node service-restart |
Restarts the background service daemon. |
pg-node service-uninstall |
Stops, disables, and removes the systemd service. |
👉 Multi-node support: Pass --name <NAME> to any node command to manage multiple instances independently on a single server (e.g. pg-node --name node2 status).
PasarGuard supports 5 database engines tailored for different workloads:
| Engine | Ideal Workload | Admin Web UI | Concurrency Mechanism |
|---|---|---|---|
| SQLite | Under 500 active users | Embedded | WAL mode (PRAGMA wal_checkpoint) |
| MySQL 8.0 | General multi-service | phpMyAdmin (port 8010) | InnoDB transactions |
| MariaDB | High-performance open alternative | phpMyAdmin (port 8010) | Aria / InnoDB |
| PostgreSQL 17 | 1,000+ concurrent clients | pgAdmin 4 (port 8010) | PgBouncer transaction pooling (port 6432) |
| TimescaleDB | High-throughput metrics & analytics | pgAdmin 4 (port 8010) | Hypertables + PgBouncer pooling |
👉 Read the full database tuning guide in docs/database-configurations.md.
The management script backs up application settings, persistent files and consistent database snapshots. New backups also record actual image digests, source database versions and a SHA256 payload inventory.
- Run
pasarguard backupfor an immediate backup, or configure scheduled Telegram delivery withpasarguard backup-service(including optional HTTP/SOCKS proxy). - Use
pasarguard restore /path/to/backup.zip --checkto validate a downloaded archive and display its source versions without changing services. - Ordinary restore checks engine/version compatibility and supports TimescaleDB conversion using a temporary container. SQL imports do not provide whole-host rollback; keep a separate backup before replacing an existing installation.
Install only the management script on the new host (install-script), copy the
complete backup there, then run:
sudo pasarguard restore /root/backup.zip --check
sudo pasarguard restore /root/backup.zip --freshFresh recovery uses the images recorded in a new backup and starts the database
before the panel. It refuses existing storage and never guesses the source
version from latest. Legacy archives remain supported by ordinary restore.
See the English recovery runbook or
راهنمای فارسی بازیابی for old backups,
multipart archives, offline images, and post-recovery checks.
PasarGuard provides 4 SSL operational modes:
- Let's Encrypt Domain: Fully automated HTTP-01 challenge verification via
acme.sh. - Let's Encrypt IP: Short-lived public IP certificates when no domain is configured.
- Custom Certificate: Bring your own CA-signed certificate chain and private key.
- Node Self-Signed with SAN: Automatic Subject Alternative Name (SAN) generation for remote nodes with private key permissions hardened to
0600.
👉 Read the full security and certificate guide in docs/ssl-and-certificates.md.
For servers operating under Iranian network sanctions and international filtering:
mirror.shBenchmark Suite: Measures latency and throughput against domestic Debian, Ubuntu, and Docker Registry mirrors (ArvanCloud, HamDocker, IranServer, MobinHost, IUT) and automatically configures/etc/apt/sources.listand/etc/docker/daemon.json.- Standalone Offline Bundles: Pre-packaged tarballs containing all required compose templates and offline scripts without requiring GitHub access during installation.
👉 Read the English standalone guide in docs/offline-and-sanctions.md or the راهنمای فارسی.
| Guide | Description |
|---|---|
| CLI Reference | Full command syntax, options, directory paths, and exit codes for Panel and Node. |
| Backup & Disaster Recovery | Backup architecture, Telegram automation, proxy routing, and TimescaleDB migrations. |
| Database Configurations | Engine comparisons, PgBouncer pooling, pgAdmin/phpMyAdmin, and memory tuning. |
| SSL & TLS Certificates | Let's Encrypt ACME setup, custom certs, SAN entries, and node TLS verification. |
| Offline & Sanctions Guide | Domestic mirror benchmarking (mirror.sh) and air-gapped standalone deployment. |
| Environment Variables | Complete .env configuration dictionary for Panel and Worker Nodes. |
Contributions are welcome! Please review CONTRIBUTING.md for development workflows and coding standards.
PasarGuard includes a master test runner executing all unit and safety test suites:
bash tests/run_all.shThis project is licensed under the terms of the repository's open source license.