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