forje-cloud 0.1.0__tar.gz

forje_cloud-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build
+build/
+dist/
+PKG-INFO
+
+# Environments
+.venv/
+venv/
+env/
+
+# Secrets
+.env
+*.pem
+*.key
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# forje-cloud output
+INFRASTRUCTURE.md
+recovery-compose.yml
+runs.jsonl

forje_cloud-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matheus Rodrigues Trindade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forje_cloud-0.1.0/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: forje-cloud
+Version: 0.1.0
+Summary: Idempotent server provisioning: Docker Swarm, Traefik and Cloudflare Tunnel, with rollback, backups and AI-explained alerts.
+Author-email: Matheus Rodrigues Trindade <contact@forjelo.com>
+Maintainer-email: Matheus Rodrigues Trindade <contact@forjelo.com>
+License: MIT
+License-File: LICENSE
+Keywords: backup,cloudflare,cloudflared,devops,docker,homelab,idempotent,infrastructure,monitoring,provisioning,self-hosted,swarm,traefik,tunnel,vps
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# forje-cloud
+
+[![PyPI](https://img.shields.io/pypi/v/forje-cloud.svg)](https://pypi.org/project/forje-cloud/)
+[![Python](https://img.shields.io/pypi/pyversions/forje-cloud.svg)](https://pypi.org/project/forje-cloud/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#no-dependencies)
+[![Platform](https://img.shields.io/badge/platform-Debian%20%7C%20Ubuntu-orange.svg)](#requirements)
+[![Status](https://img.shields.io/badge/status-preview-yellow.svg)](#status-of-this-release)
+
+**A production server, from a bare Debian box, in one command.**
+
+Containers, HTTPS, backups, monitoring and hardening — provisioned, verified,
+and documented. Every step checks what already exists and leaves it alone.
+
+```bash
+pip install forje-cloud
+forje-cloud setup
+```
+
+---
+
+## What you get
+
+A server that publishes applications over HTTPS **without opening a single
+inbound port**.
+
+| | |
+|---|---|
+| **Docker Swarm** | Encrypted secrets, rolling updates, room to add machines. |
+| **Traefik** | Routes hostnames to containers, using labels. |
+| **Cloudflare Tunnel** | A `cloudflared` container holds one outbound connection that carries all inbound traffic. The firewall stays closed. |
+| **Wildcard DNS + TLS** | `*.example.com` resolves and is certificated once. Every application deployed afterwards is a routing label and nothing else. |
+| **Local image registry** | Build on the machine, deploy from the machine. |
+| **Backups to Cloudflare R2** | Volumes, databases and images — off the machine, supervised, with retention. |
+| **AI-explained monitoring** | Logs are classified; anything serious is explained by Claude or GPT and delivered to Telegram. |
+| **Hardening** | Firewall, intrusion blocking, key-only SSH. |
+| **Tamper-evident audit log** | Every entry carries the hash of the one before it. |
+| **Self-documenting** | Every run writes an `INFRASTRUCTURE.md` describing the machine as it is. |
+
+---
+
+## Why
+
+Provisioning scripts assume a clean machine. Real machines are never clean.
+
+Docker is installed, but not in Swarm mode. A reverse proxy is running, but as a
+plain container. A tunnel was set up months ago and nobody wants to touch it.
+The deploy user exists but is not in the `docker` group.
+
+Running a bootstrap script on that machine is a gamble: it either fails on the
+first step that was already done, or it redoes the step and takes down whatever
+was working.
+
+`forje-cloud` checks before it acts. Every step answers *"does this already
+exist, and is it correct?"* before touching anything.
+
+---
+
+## How traffic reaches an application
+
+Nothing listens on a public port. A container named `cloudflared` runs on the
+host network and opens a single outbound connection to Cloudflare. Inbound
+requests travel back down that connection.
+
+```
+browser ──HTTPS──> Cloudflare ──tunnel──> cloudflared ──HTTP──> Traefik ──> app
+                       │                       │
+                  TLS ends here          outbound only,
+                                        no port is opened
+```
+
+**TLS terminates at Cloudflare.** Inside the machine everything speaks plain
+HTTP, so Traefik never holds a certificate, never contacts a certificate
+authority, and never needs port 443.
+
+Provisioning wires this together in three parts:
+
+1. **The tunnel** is created through the Cloudflare API, and its ingress rules
+   are configured to forward to `http://127.0.0.1:80` — the port Traefik
+   publishes on the loopback address. A tunnel with no ingress rules
+   authenticates, reports healthy, and routes nothing; configuring them is what
+   makes it carry traffic.
+
+2. **Two DNS records** are created, both pointing at the tunnel: the apex
+   (`example.com`) and the wildcard (`*.example.com`). The wildcard is the
+   reason a new application needs no DNS work at all — any subdomain already
+   resolves, and already has a certificate.
+
+3. **The `cloudflared` container** receives the connector token as a root-only
+   file rather than a command-line flag, so `docker inspect` and `ps` cannot
+   read it.
+
+### Deploying an application afterwards
+
+Once the tunnel and the wildcard exist, publishing a new application is five
+labels. No DNS record, no certificate, no port.
+
+```yaml
+services:
+  myapp:
+    image: 127.0.0.1:5000/myapp:20260711-1420
+    networks: [edge]
+    deploy:
+      # Traefik reads these from the Swarm service, not the container.
+      labels:
+        - "traefik.enable=true"
+        - "traefik.swarm.network=edge"
+        - "traefik.http.routers.myapp.rule=Host(`myapp.example.com`)"
+        - "traefik.http.routers.myapp.entrypoints=web"
+        - "traefik.http.services.myapp.loadbalancer.server.port=8000"
+
+networks:
+  edge:
+    external: true
+```
+
+`docker stack deploy`, and `https://myapp.example.com` is live.
+
+---
+
+## Guided setup
+
+```bash
+forje-cloud setup
+```
+
+Every question explains what the value is for, in one line, without jargon.
+Every section can be skipped — skipping backups means no backups, not a crash.
+Nothing is executed until the configuration is shown and confirmed.
+
+```
+── Public access (Cloudflare) ────────────────────────────
+   Cloudflare puts your apps online without opening any port on
+   this machine. It also provides HTTPS certificates automatically.
+
+ ? Publish this server through Cloudflare? [Y/n]
+
+ ? Domain
+   A domain you own, already added to Cloudflare. Example: example.com
+   >
+```
+
+---
+
+## The other commands
+
+```bash
+forje-cloud status    # what this machine already has
+forje-cloud plan      # what a run would change, without changing it
+forje-cloud apply     # provision from flags and environment, no prompts
+forje-cloud restore   # bring back volumes, databases and images
+forje-cloud compose   # reconstruct a Compose file for every running workload
+forje-cloud verify    # has the audit log been tampered with?
+forje-cloud docs      # regenerate the infrastructure document
+```
+
+A run on an already-provisioned machine:
+
+```
+ • hostname        already 'example-host'
+ • deploy-user     account 'deploy' exists
+ • docker          Docker version 28.0.0
+ ✔ docker-group    added 'deploy' to the docker group
+ ✔ swarm           initialized (advertise address 192.0.2.10)
+ • network         overlay 'edge' exists
+ ▲ traefik         running traefik:v2.11, expected traefik:v3.3
+```
+
+`•` already present · `✔` configured now · `▲` **exists but diverges**
+
+---
+
+## Drift is not absence
+
+Most tools treat "wrong" and "missing" as the same thing, and overwrite both.
+
+They are not the same thing. Traefik v2 and v3 read different label syntax: v3
+uses a dedicated `swarm` provider and reads `traefik.swarm.network`, where v2
+used `docker` with `swarmMode: true` and read `traefik.docker.network`. The two
+are not interchangeable — v3 labels on a v2 proxy are ignored, which leaves an
+application running but unrouted, with no error anywhere.
+
+So a proxy on the wrong major version is not a gap to fill. It is a running
+system whose every routing label would have to be rewritten at once. That is a
+migration, and a migration is a decision.
+
+`forje-cloud` reports drift and stops.
+
+---
+
+## Backups
+
+A backup stored on the machine it protects is not a backup. Archives are
+uploaded to Cloudflare R2, off the machine.
+
+Three things are captured, because restoring any two of them is not enough:
+
+- **Volumes** — archived with `zstd`, which is faster and smaller than gzip.
+- **Databases** — dumped with each engine's own tool. Postgres, MySQL, MariaDB,
+  MongoDB and Redis are recognised by image family, so `postgres:16-alpine` and
+  `pgvector/pgvector` are both handled. Copying live database files instead can
+  catch them mid-write, producing an archive that will not restore.
+- **Images** — the local registry. Without them, a rebuilt machine has stack
+  files referencing images that exist nowhere, and every application must be
+  rebuilt from source before it can start.
+
+The service is supervised: a failed cycle is retried, and if the process dies
+Swarm restarts it. The schedule is configurable — daily by default, with
+retention in days.
+
+Every backup carries a manifest naming what it holds, so restore reads it rather
+than inferring intent from filenames.
+
+### Restoring
+
+```bash
+forje-cloud restore
+```
+
+Pick a backup, then pick what to bring back — by number, by range, or `all`.
+Recovering a machine that ran eight workloads means dozens of volumes, and
+restoring them one command at a time is where mistakes happen.
+
+### The Compose file nobody kept
+
+```bash
+forje-cloud compose
+```
+
+Servers accumulate stacks deployed from files that were never committed
+anywhere. This reads the running services back out of Swarm and reconstructs a
+single Compose file covering every workload — images, volumes, networks,
+secrets, routing labels.
+
+A copy is written into every backup. After a total loss: restore the archives,
+deploy the file, and the machine is back.
+
+---
+
+## Monitoring
+
+Container logs are read on a schedule. Lines are matched against patterns and
+scored for severity — out-of-memory kills, disk exhaustion, crash loops,
+certificate failures, authentication attempts.
+
+Only findings above the threshold are escalated. Those go to Claude or GPT,
+which answers three questions: **what happened, what likely caused it, and what
+to do about it.** The answer arrives on Telegram.
+
+Raw logs never leave the machine. Only the classified findings are sent, which
+are smaller, cheaper, and do not carry whatever a log line happened to contain.
+
+Identical alerts are suppressed for an hour, so one incident produces one alert
+rather than fifty.
+
+---
+
+## An audit log you can trust
+
+Every entry carries the hash of the entry before it.
+
+```bash
+$ forje-cloud verify
+✖ audit log   entry #4 (step=firewall) was modified: hash does not match
+```
+
+Editing or deleting any past record breaks the chain. This does not prevent
+tampering; it makes tampering evident.
+
+---
+
+## It documents itself
+
+Every run writes `INFRASTRUCTURE.md`: a diagram of how traffic reaches an
+application, what is running, what an application must declare to be deployed
+here, and what must never appear in its Compose file.
+
+Written from the results of the run, so it describes the machine as it is.
+
+---
+
+## Safety
+
+**Closing SSH requires a working tunnel.** The step refuses otherwise. Closing
+the only way in, with no working alternative, cannot be undone — the channel
+needed to revert is the one being closed.
+
+**Destructive steps require confirmation.** Always explicit, never implied.
+
+**Credentials are never written down.** The sudo password is passed on stdin,
+never in `argv` (visible through `ps`) and never in the environment (visible
+through `/proc`). Service credentials become Docker secrets, encrypted at rest.
+Nothing is written to the audit log or the generated document.
+
+**Sudo is scoped.** The deploy account gets `NOPASSWD` for an enumerated list of
+commands, never `ALL`.
+
+**Configuration is validated before it is loaded.** `sshd -t` and `visudo -cf`
+run first. An invalid file is reverted, not applied.
+
+---
+
+## Requirements
+
+- A Debian-based Linux machine — Debian or Ubuntu. VPS or bare metal.
+- Python 3.9 or newer.
+- Root, or an account with `sudo`.
+- Optional, for public access: a domain on Cloudflare.
+- Optional, for backups: a Cloudflare R2 bucket.
+- Optional, for alerts: a Telegram bot and an Anthropic or OpenAI API key.
+
+## No dependencies
+
+Standard library only. A tool that provisions a machine should not require the
+machine to be provisioned first.
+
+---
+
+## Status of this release
+
+**v0.1.0 is published for review, not for production use.**
+
+It ships with a passing test suite and code that is complete and, as far as the
+suite reaches, correct. What it has not yet had is a full run against a real VPS,
+from a clean install through to a working tunnel. Until that has happened,
+calling it ready would be a claim this release cannot support.
+
+So it is published as what it is: a first cut, open for inspection, while
+validation on real hardware is underway.
+
+**v0.1.1 will be the first release intended for real use.** It follows shortly.
+
+Read the code. Run the tests. Send corrections. Just don't point it at a machine
+that matters yet.
+
+---
+
+## Contributing
+
+Contributions are welcome and actively wanted — corrections, criticism of the
+design, or an account of what happened when the tool met a real machine.
+
+A public repository is not yet available, so the way in is email:
+
+- **contact@forjelo.com**
+- **matheusrodriguestrindade3@gmail.com**
+
+Patches, findings and hard questions all land in the same place.
+
+---
+
+## License
+
+MIT © Matheus Rodrigues Trindade