@netrunner714/pegas 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +267 -2
- package/dist/index.js +2885 -0
- package/package.json +48 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 NETRUNNER714
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,268 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pegas
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Agent-native zero-config L7 reverse proxy orchestrator for Docker.**
|
|
4
|
+
> Host unlimited websites and APIs on a single VPS with zero port conflicts, automatic Let's Encrypt SSL, and zero-downtime hot reloads. Built specifically to be rock-solid for human developers and autonomous AI coding agents (Cursor, Claude Code, Cline, Copilot).
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/@netrunner714/pegas)
|
|
7
|
+
[](https://github.com/netrunner714/pegas/actions/workflows/ci.yml)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](package.json)
|
|
10
|
+
[](package.json)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## ⚡ The Problem: VPS Port Collisions & Dev Chaos
|
|
15
|
+
|
|
16
|
+
When hosting multiple Dockerized web projects on a single VPS ($5–20/mo):
|
|
17
|
+
|
|
18
|
+
* **The 80/443 Port Trap**: Every application's `docker-compose.yml` tries to bind `ports: - "80:80"` and `"443:443"`. The first app succeeds; every subsequent app crashes with `bind: address already in use`.
|
|
19
|
+
* **DNS Split-Brain Collisions**: When multiple projects share an external Docker network with generic service names (like `web` or `app`), Docker's embedded DNS round-robins requests across completely unrelated projects.
|
|
20
|
+
* **Cold Starts & 502 Bad Gateway**: Deploying an app that takes 10–30s to boot (Prisma migrations, Next.js build) causes immediate 502 errors if reverse proxy routes are updated prematurely.
|
|
21
|
+
* **Domain Hijacking**: Project B accidentally configures a domain already owned by Project A in its compose/caddy files, breaking routing.
|
|
22
|
+
* **Disk Exhaustion**: Unbounded Docker container logs silently fill the server disk until Docker crashes.
|
|
23
|
+
* **Dev Sprawl**: Developers juggle 3 terminal tabs for local development: one for Docker databases, one for Vite/Next.js, and one for local HTTPS / ngrok.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 💡 The Pegas Architecture
|
|
28
|
+
|
|
29
|
+
Pegas standardizes your multi-app VPS around a unified, ultra-lightweight **Caddy 2** gateway:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
Internet (HTTP :80 / HTTPS :443)
|
|
33
|
+
│
|
|
34
|
+
▼
|
|
35
|
+
┌─────────────────────────────┐
|
|
36
|
+
│ Pegas Caddy Gateway │ (~30 MB RAM)
|
|
37
|
+
│ (Auto Let's Encrypt SSL) │
|
|
38
|
+
└──────────────┬──────────────┘
|
|
39
|
+
│
|
|
40
|
+
Docker Network: │ pegas-network
|
|
41
|
+
┌───────────────────────┴───────────────────────┐
|
|
42
|
+
▼ ▼
|
|
43
|
+
┌──────────────────┐ ┌──────────────────┐
|
|
44
|
+
│ Project Alpha │ │ Project Beta │
|
|
45
|
+
│ alias: │ │ alias: │
|
|
46
|
+
│ alpha-web:3000 │ │ beta-web:8080 │
|
|
47
|
+
└──────────────────┘ └──────────────────┘
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
1. **Ultra-Lightweight**: Uses **~30 MB of RAM** for the entire reverse proxy gateway (vs 1–2 GB for Coolify or Dokku).
|
|
51
|
+
2. **Zero Port Collisions**: Only the Pegas gateway binds host ports `80` and `443`. Containers communicate internally over `pegas-network`.
|
|
52
|
+
3. **Project-Scoped DNS Aliases**: Automatically scopes container aliases (`<projectName>-<service>`), preventing round-robin split-brain collisions.
|
|
53
|
+
4. **Readiness Probe**: Waits for containers to become healthy before reloading Caddy — zero 502 Bad Gateway errors on deploy.
|
|
54
|
+
5. **Domain Anti-Hijacking**: Validates that target domains are not already claimed by another project on the server.
|
|
55
|
+
6. **Automatic Docker Log Rotation**: Configures `max-size: 50m` / `max-file: 3` to keep server disks clean.
|
|
56
|
+
7. **Smart Local Dev (`pegas dev`)**: Native HTTPS proxy on unprivileged ports (8443+) with optional automatic database boot and teardown.
|
|
57
|
+
8. **Zero Dependencies**: 100% standard Node.js stdlib. No heavy npm dependency trees.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 🚀 Quickstart (30 Seconds)
|
|
62
|
+
|
|
63
|
+
### Step 1: Initialize in Your Project
|
|
64
|
+
|
|
65
|
+
Run inside any web application directory with a `package.json` or `docker-compose.yml`:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npx @netrunner714/pegas init
|
|
69
|
+
# or: pnpm add -D @netrunner714/pegas && pnpm pegas init
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**What `pegas init` does automatically:**
|
|
73
|
+
- 🔍 **Discovers Services**: Detects web and infra services from your `docker-compose.yml` (e.g. `web:3000` or `8080:80`).
|
|
74
|
+
- ✂️ **Compose Surgery**:
|
|
75
|
+
- Removes public web port mappings (`80:80`, `3000:3000`) to eliminate host port conflicts.
|
|
76
|
+
- Preserves infrastructure ports (Postgres `5432:5432`, Redis `6379:6379`).
|
|
77
|
+
- Injects `expose` directives for internal proxying.
|
|
78
|
+
- Attaches the web service to `pegas-network` with a project-scoped alias (`<projectName>-web`).
|
|
79
|
+
- Injects Docker logging rotation (`max-size: 50m`, `max-file: 3`).
|
|
80
|
+
- 📜 **Scaffolds `pegas.json`**: Creates a declarative contract with slug-derived dev (`<project>.localhost`) and prod (`<project>.com`) domains.
|
|
81
|
+
- ⚡ **Injects Scripts**: Wraps `npm run dev` with `pegas dev` and adds `npm run deploy` (`pegas deploy`) in `package.json`.
|
|
82
|
+
- 🛡️ **Protects VCS**: Adds `.pegas` to `.gitignore`.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
### Step 2: Local Development with Smart Infra Boot
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npm run dev
|
|
90
|
+
# or: npx pegas dev -- next dev
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
* **Zero-Config Local HTTPS**: Starts local native Caddy on unprivileged ports (`https://<project>.localhost:8443`).
|
|
94
|
+
* **Smart Infra Boot (Optional)**: Automatically starts databases (Postgres, Redis, MongoDB, MySQL) via `docker compose up -d <services>` when enabled:
|
|
95
|
+
```bash
|
|
96
|
+
npx pegas dev --infra -- npm run dev
|
|
97
|
+
```
|
|
98
|
+
*(Or enable permanently for the team via `"bootInfra": true` in `pegas.json`).*
|
|
99
|
+
* **Graceful Teardown**: Pressing `Ctrl+C` safely stops databases (`docker compose stop`) without deleting volumes or losing data.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
### Step 3: Deploy to VPS
|
|
104
|
+
|
|
105
|
+
Commit your code and pull it onto your VPS, then run:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npm run deploy
|
|
109
|
+
# or: npx pegas deploy
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```text
|
|
113
|
+
🚀 [1/3] Starting project containers with Docker Compose...
|
|
114
|
+
⏳ Checking container readiness for: web...
|
|
115
|
+
🟢 Service 'web' is ready to accept traffic
|
|
116
|
+
📄 [2/3] Generated route config: /home/vibe/gateway/conf.d/shop.caddy
|
|
117
|
+
🔄 [3/3] Validating and hot-reloading Caddy gateway...
|
|
118
|
+
🎉 Project 'shop' successfully deployed to Pegas gateway!
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
* **Readiness Verification**: Verifies container is running and healthy before updating routes.
|
|
122
|
+
* **DNS Pre-Flight Check**: Checks DNS A-records against server public IP to protect Let's Encrypt rate limits (`--strict-dns` in CI).
|
|
123
|
+
* **Anti-Hijacking Check**: Rejects deployment if another project on the server already claims the domain.
|
|
124
|
+
* **Zero-Downtime Hot Reload**: Replaces routes atomically with instant rollback if configuration validation fails.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 📊 Global Server Dashboard: `pegas ls`
|
|
129
|
+
|
|
130
|
+
Inspect all active projects deployed on the server with real-time Docker container states:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
npx pegas ls
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
🚀 Pegas Global Dashboard — Active Projects in /home/user/gateway:
|
|
138
|
+
|
|
139
|
+
┌───────────────┬──────────────────────────────────────────┬──────────────────────┬─────────────────┐
|
|
140
|
+
│ PROJECT │ DOMAINS │ UPSTREAM │ STATUS │
|
|
141
|
+
├───────────────┼──────────────────────────────────────────┼──────────────────────┼─────────────────┤
|
|
142
|
+
│ project-alpha │ project-alpha.com, www.project-alpha.com │ project-alpha-web:80 │ 🟢 Up 2 hours │
|
|
143
|
+
│ project-beta │ project-beta.com, www.project-beta.com │ project-beta-web:80 │ 🟢 Up 45 minutes│
|
|
144
|
+
│ my-blog │ blog.example.com │ my-blog-web:3000 │ 🔴 Exited (1) │
|
|
145
|
+
└───────────────┴──────────────────────────────────────────┴──────────────────────┴─────────────────┘
|
|
146
|
+
|
|
147
|
+
Total: 3 active projects
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## 📄 The Declarative Contract: `pegas.json`
|
|
153
|
+
|
|
154
|
+
The `pegas.json` file is version-controlled in your repository:
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"$schema": "https://netrunner714.ru/schemas/pegas.json",
|
|
159
|
+
"projectName": "my-cool-app",
|
|
160
|
+
"bootInfra": true,
|
|
161
|
+
"services": {
|
|
162
|
+
"web": {
|
|
163
|
+
"upstream": "web:3000",
|
|
164
|
+
"domains": {
|
|
165
|
+
"dev": [
|
|
166
|
+
"my-cool-app.localhost"
|
|
167
|
+
],
|
|
168
|
+
"prod": [
|
|
169
|
+
"mycoolapp.com",
|
|
170
|
+
"www.mycoolapp.com",
|
|
171
|
+
"магазин.рф"
|
|
172
|
+
]
|
|
173
|
+
}
|
|
174
|
+
},
|
|
175
|
+
"api": {
|
|
176
|
+
"upstream": "backend:8000",
|
|
177
|
+
"domains": {
|
|
178
|
+
"dev": [
|
|
179
|
+
"api.my-cool-app.localhost"
|
|
180
|
+
],
|
|
181
|
+
"prod": [
|
|
182
|
+
"api.mycoolapp.com"
|
|
183
|
+
]
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Key Contract Options:
|
|
191
|
+
* **`projectName`**: Scopes network aliases (`<projectName>-web:3000`) and route files (`conf.d/<projectName>.caddy`).
|
|
192
|
+
* **`bootInfra`**: (Boolean) When `true`, `pegas dev` automatically boots Docker Compose databases and infrastructure services.
|
|
193
|
+
* **`domains.dev`**: Local domains routed by `pegas dev` to `localhost:<port>`.
|
|
194
|
+
* **`domains.prod`**: Production domains routed by `pegas deploy` to `<projectName>-<service>:<port>`.
|
|
195
|
+
* **IDN / Cyrillic Support**: Full native support for non-Latin domains (e.g. `магазин.рф`). Converted safely to Punycode (`xn--...`) for filesystem compatibility while Caddy handles TLS certificates automatically.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## 🛡️ SRE Protections & Reliability
|
|
200
|
+
|
|
201
|
+
| Feature | Protection | Behavior |
|
|
202
|
+
| :--- | :--- | :--- |
|
|
203
|
+
| **Readiness Probe** | Prevents `502 Bad Gateway` | Polls Docker container state and Docker Healthcheck before updating Caddy routes. |
|
|
204
|
+
| **Domain Anti-Hijacking** | Prevents Route Collision | Scans existing project configs in `conf.d/` and halts if another project already owns the domain. |
|
|
205
|
+
| **DNS Pre-Flight** | Prevents ACME Rate Limits | Resolves A-records before deployment; alerts developer if DNS has not propagated to this server (`--strict-dns` in CI). |
|
|
206
|
+
| **Docker Log Rotation** | Prevents VPS Disk Full | Automatically configures `driver: json-file`, `max-size: 50m`, `max-file: 3` for all services. |
|
|
207
|
+
| **Local Delegation** | Prevents CLI Version Drift | Global CLI automatically delegates execution to local `node_modules/pegas` when present in project root. |
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## 🛠️ CLI Reference
|
|
212
|
+
|
|
213
|
+
```
|
|
214
|
+
pegas <command> [options]
|
|
215
|
+
|
|
216
|
+
COMMANDS:
|
|
217
|
+
init Init Pegas in current project (or --server for VPS gateway)
|
|
218
|
+
dev [-- <command>] Run local dev HTTPS proxy and start dev command (e.g. pegas dev -- next dev)
|
|
219
|
+
deploy Declarative deploy: configure Caddy routes & start containers
|
|
220
|
+
down Tear down project containers and remove Caddy routes
|
|
221
|
+
add <domain> [options] Imperatively route a domain to an internal container upstream
|
|
222
|
+
list, ls List all active domain routes and Docker container health
|
|
223
|
+
remove, rm <domain> Delete route and reload Caddy
|
|
224
|
+
reload Validate and hot-reload Caddy configuration
|
|
225
|
+
status Check Docker and gateway health
|
|
226
|
+
llms Print machine-readable LLM context
|
|
227
|
+
|
|
228
|
+
OPTIONS FOR 'dev':
|
|
229
|
+
--infra Boot infrastructure services defined in docker-compose.yml
|
|
230
|
+
--no-infra Do not boot infrastructure services even if enabled in pegas.json
|
|
231
|
+
|
|
232
|
+
OPTIONS FOR 'deploy':
|
|
233
|
+
--strict-dns Abort deployment if DNS records do not match server IP
|
|
234
|
+
--skip-dns-check Bypass DNS pre-flight verification
|
|
235
|
+
--skip-readiness Skip container readiness check
|
|
236
|
+
|
|
237
|
+
GLOBAL OPTIONS:
|
|
238
|
+
--gateway-dir <path> Override path to gateway directory
|
|
239
|
+
--dry-run Print generated configs without applying
|
|
240
|
+
--json Output machine-readable JSON (ideal for AI agents)
|
|
241
|
+
-h, --help Show help
|
|
242
|
+
-v, --version Show version
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## 🤖 Built for AI Coding Agents
|
|
248
|
+
|
|
249
|
+
Pegas is designed from the ground up for **Agent-Driven Development**:
|
|
250
|
+
|
|
251
|
+
* **Machine-Readable CLI**: Every command supports `--json` for structured input/output.
|
|
252
|
+
* **Deterministic Configuration**: No interactive prompts that cause agents to hang.
|
|
253
|
+
* **Project Guidelines**: Generates `docs/pegas.md` in initialized projects and provides `npx pegas llms` / `llms.txt` so tools like Cursor, Claude Code, Cline, and GitHub Copilot immediately understand how to deploy without modifying host Nginx or breaking other containers.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## 🔒 Security & Best Practices
|
|
258
|
+
|
|
259
|
+
* **No Docker Socket in Gateway**: Unlike Traefik, Pegas does not mount `/var/run/docker.sock` into the web-facing proxy container, eliminating privilege escalation vulnerabilities.
|
|
260
|
+
* **Default Security Headers**: Automatically applies `Strict-Transport-Security` (HSTS), `X-Content-Type-Options: nosniff`, and `Referrer-Policy: strict-origin-when-cross-origin`.
|
|
261
|
+
* **Rootless Local Dev**: `pegas dev` uses `skip_install_trust` and unprivileged ports, requiring zero root/sudo permissions.
|
|
262
|
+
* **Automatic Rollback**: If syntax validation fails during reload, the previous configuration is immediately restored.
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## 📄 License
|
|
267
|
+
|
|
268
|
+
MIT © [NETRUNNER714](https://netrunner714.ru)
|