Metadata-Version: 2.4
Name: proxy-deploy
Version: 1.0.0
Summary: Declarative sing-box deployment and management:  manifest-driven config generation, credential persistence, SSH deploy,  diagnostics (doctor), and server provisioning (bootstrap).
Project-URL: Homepage, https://github.com/koufodakoufo/proxy-deploy
Project-URL: Repository, https://github.com/koufodakoufo/proxy-deploy
Project-URL: Issues, https://github.com/koufodakoufo/proxy-deploy/issues
Author: koufodakoufo
License: MIT
License-File: LICENSE
Keywords: deployment,proxy,reality,shadowsocks,sing-box,vless
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cryptography>=49.0.0
Requires-Dist: qrcode[pil]>=8.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.27.0
Description-Content-Type: text/markdown

# proxy-deploy
[![PyPI - Version](https://img.shields.io/pypi/v/proxy-deploy)](https://pypi.org/project/proxy-deploy/)
[![Python Versions](https://img.shields.io/pypi/pyversions/proxy-deploy)](https://pypi.org/project/proxy-deploy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

My own proxy deployment and management system, established from scratch. 
Based on sing-box core, and config management/generation is realized by Python.

## Features
- 🧾 Declarative manifest: `nodes.toml` act as the single source of truth (Infrastructure as Code)
- 🔐 Credential persistence: the state file `secrets.json` makes re-running idempotent, retains previous credentials
- 🧩 Multi-protocol: VLESS+REALITY and Shadowsocks 2022 (supports extension in the future)
- 🚀 One-command deploy: SSH deploy from local or "self-deploy" on the server, along with validation and survival checking
- 🩺 `doctor`: Post-deployment automated diagnostics (connectivity, service status, ports, REALITY handshake events, clock skew, and binary versions)
- 🥾 `bootstrap`: One-click bare-metal installation (featuring version locking + SHA256 checksums, avoiding blind `curl | bash` executions)
- 🔗 Generates sharing links and QR codes compatible with V2RayN, Shadowrocket, etc.
- ✅ Covered by 24 rigorous pytest cases ensuring pipeline stability

## Installation
Requires Python 3.12+. With [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv tool install proxy-deploy
```

Or with pipx: `pipx install proxy-deploy`
Or run without installing: `uvx proxy-deploy --help`

Enable shell completion (commands, options, file paths, and SSH hosts from `~/.ssh/config`):

```bash
proxy-deploy --install-completion  # then restart your shell
```

## Usage (from scratch)
1. Configure an SSH alias in `~/.ssh/config` for key-based login.
2. `proxy-deploy bootstrap -H <alias>` — provision the bare-metal server (once per server; omit `-H` when running on the server itself).
3. Copy `config/nodes.example.toml` to `nodes.toml` and declare your nodes.
4. `proxy-deploy generate-all -m nodes.toml` — generate configs and state.
5. Open the node ports in BOTH firewalls: the cloud provider's security list AND system iptables (SS2022 needs both TCP and UDP).
6. `proxy-deploy deploy config/config.json -H <alias>` — deploy.
7. `proxy-deploy doctor -H <alias>` — verify deployment health.
8. Import the printed share links / QR codes into your client.

## Commands
| Command | Purpose |
|---|---|
| `generate-all` | Generate multi-node configs from the manifest (stateful, stable credentials) |
| `generate` | Generate a stateless, one-off node (quick demos / temporary use) |
| `deploy` | Deploy a config (locally, or remotely via SSH with `-H`) |
| `list` | List nodes currently running on a server |
| `doctor` | Run post-deployment diagnostics (locally or over SSH) |
| `bootstrap` | Install sing-box + systemd service on a fresh server (locally or over SSH) |

## Topologies
Every management command works in two modes:
- **Remote** (`-H <alias>`): run from a management machine (e.g. your laptop), operating the server over SSH/SCP.
- **Local** (omit `-H`): run on the server itself ("self-deploy") — only Linux + sudo needed, no SSH setup.

Local-mode note: `doctor` skips TCP-reachability and clock-skew checks (meaningful only from a second machine).

## Credential & state model
Intent (nodes.toml, human-written) + State (secrets.json, machine-written, gitignored) → Resolved Credentials.
- Precedence: Explicitly defined in manifest > State file > Freshly generated.
- Deleting a node from the manifest equals taking it offline.
- Changing a port instantiates a completely new node.

## Development
```bash
git clone https://github.com/koufodakoufo/proxy-deploy
cd proxy-deploy
uv sync # install env incl. dev dependencies
uv run pytest -v # 27 test cases
uvx ruff check src tests # lint
```

## Architecture
```text
proxy-deploy/
├── pyproject.toml              # Project metadata, dependencies, and build config
├── uv.lock                     # Locked dependencies
├── .python-version             # Python 3.12
├── .gitignore / README.md
│
├── src/proxy_deploy/           # Python package (distribution name: proxy-deploy)
│   ├── __init__.py
│   ├── cli.py                  # 🎮 CLI entry point
│   ├── manifest.py             # 🧾 Manifest model: loading, validation, credential resolution
│   ├── state.py                # 🔐 State file I/O (secrets.json)
│   ├── credentials.py          # 🔑 Credential generation (UUID / X25519 / short_id / SS2022 keys)
│   ├── config_builder.py       # 🏗️ config.json builder (protocol dispatching)
│   ├── share_link.py           # 🔗 vless:// and ss:// link generators
│   ├── qr_code.py              # 📷 QR code generator
│   ├── deploy.py               # 🚀 SSH deployment and remote config fetching
│   ├── doctor.py               # 🩺 Post-deployment diagnostics
│   └── bootstrap.py            # 🥾 Bare-metal installer
│
├── tests/                      # pytest test suite
├── config/                     # nodes.toml (manifest), secrets.json (gitignored), templates
├── docs/                       # Personal documentation and references
├── scripts/                    # Auxiliary scripts (reserved)
├── bin/                        # Local sing-box binaries (gitignored)
└── downloads/                  # Download cache (gitignored)
```

## Credits
- [sing-box](https://github.com/SagerNet/sing-box) - the core this tool deploys and manages.
- [Xray-core](https://github.com/XTLS/Xray-core) - reference implementation of VLESS/REALITY. 
- Inspired by [Alvin9999-newpac/fanqiang](https://github.com/Alvin9999-newpac/fanqiang).
- Kimi K3 and Deepseek V4.

## License
MIT License — see [LICENSE](LICENSE).