ign8saas 0.1.1__tar.gz

ign8saas-0.1.1/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: ign8saas
+Version: 0.1.1
+Summary: Ignite a multi-tenant SaaS control plane (Vaultwarden + wg-portal) fronted by Caddy on Hetzner Cloud.
+License: MIT
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Requires-Dist: cloudflare (>=3)
+Requires-Dist: cryptography (>=42)
+Requires-Dist: hcloud (>=2)
+Requires-Dist: mypy (>=1.10) ; extra == "dev"
+Requires-Dist: paramiko (>=3)
+Requires-Dist: pydantic (>=2)
+Requires-Dist: pydantic-settings (>=2)
+Requires-Dist: pytest (>=8) ; extra == "dev"
+Requires-Dist: rich (>=13)
+Requires-Dist: ruff (>=0.4) ; extra == "dev"
+Requires-Dist: typer (>=0.12)
+Description-Content-Type: text/markdown
+
+# ign8saas
+
+Ignite a multi-tenant SaaS control plane on Hetzner Cloud. One VPS runs
+**Caddy** (TLS termination + wildcard certs via Cloudflare DNS-01),
+**Vaultwarden** (Bitwarden-compatible password vault) and **wg-portal**
+(WireGuard admin UI) — reachable at three subdomains of your parent zone.
+
+## Quickstart
+
+```bash
+cp .env.example .env    # fill in Hetzner + Cloudflare credentials
+ign8saas up             # provision server + DNS + docker stack
+```
+
+## What gets provisioned
+
+For `IGN8_DOMAIN=traeck.it` you get:
+
+| Subdomain                     | Purpose                                        |
+|-------------------------------|------------------------------------------------|
+| `saas.traeck.it`              | landing page ("SaaS control plane — coming soon") |
+| `*.vaultwarden.traeck.it`     | Vaultwarden (vanity slug redirect on subdomain) |
+| `*.vpn.traeck.it`             | wg-portal (WireGuard admin UI)                 |
+
+Underneath, on a single Hetzner `cax11` VPS in `fsn1`:
+
+- Docker + Compose plugin (installed via `get.docker.com`)
+- `caddy` (`ghcr.io/caddybuilds/caddy-cloudflare:latest`) — ports 80/443, wildcard certs via DNS-01
+- `vaultwarden` (`vaultwarden/server:latest`) — signups disabled, invitations enabled
+- `wg-portal` (`ghcr.io/h44z/wg-portal:latest`) — port 51820/udp exposed for WireGuard
+- Hetzner firewall: 22 / 80 / 443 / 51820-udp only
+
+## State
+
+Local state lives under `.ign8saas/` (gitignored):
+
+- `.ign8saas/keys/ign8saas` — SSH private key for server access
+- `.ign8saas/state.json` — Hetzner IDs, IPv4
+- `.ign8saas/vaultwarden-init.json` — Vaultwarden admin token + wg-portal admin creds (chmod 600, **keep safe**)
+
+## Status
+
+This scaffold delivers the **shared infra** only. Per-customer onboarding
+(`add-customer`, `del-customer`) is stubbed — see `CLAUDE.md` for the design
+notes and the roadmap.
+
+See [CLAUDE.md](CLAUDE.md) for architecture details.
+

ign8saas-0.1.1/README.md

@@ -0,0 +1,47 @@
+# ign8saas
+
+Ignite a multi-tenant SaaS control plane on Hetzner Cloud. One VPS runs
+**Caddy** (TLS termination + wildcard certs via Cloudflare DNS-01),
+**Vaultwarden** (Bitwarden-compatible password vault) and **wg-portal**
+(WireGuard admin UI) — reachable at three subdomains of your parent zone.
+
+## Quickstart
+
+```bash
+cp .env.example .env    # fill in Hetzner + Cloudflare credentials
+ign8saas up             # provision server + DNS + docker stack
+```
+
+## What gets provisioned
+
+For `IGN8_DOMAIN=traeck.it` you get:
+
+| Subdomain                     | Purpose                                        |
+|-------------------------------|------------------------------------------------|
+| `saas.traeck.it`              | landing page ("SaaS control plane — coming soon") |
+| `*.vaultwarden.traeck.it`     | Vaultwarden (vanity slug redirect on subdomain) |
+| `*.vpn.traeck.it`             | wg-portal (WireGuard admin UI)                 |
+
+Underneath, on a single Hetzner `cax11` VPS in `fsn1`:
+
+- Docker + Compose plugin (installed via `get.docker.com`)
+- `caddy` (`ghcr.io/caddybuilds/caddy-cloudflare:latest`) — ports 80/443, wildcard certs via DNS-01
+- `vaultwarden` (`vaultwarden/server:latest`) — signups disabled, invitations enabled
+- `wg-portal` (`ghcr.io/h44z/wg-portal:latest`) — port 51820/udp exposed for WireGuard
+- Hetzner firewall: 22 / 80 / 443 / 51820-udp only
+
+## State
+
+Local state lives under `.ign8saas/` (gitignored):
+
+- `.ign8saas/keys/ign8saas` — SSH private key for server access
+- `.ign8saas/state.json` — Hetzner IDs, IPv4
+- `.ign8saas/vaultwarden-init.json` — Vaultwarden admin token + wg-portal admin creds (chmod 600, **keep safe**)
+
+## Status
+
+This scaffold delivers the **shared infra** only. Per-customer onboarding
+(`add-customer`, `del-customer`) is stubbed — see `CLAUDE.md` for the design
+notes and the roadmap.
+
+See [CLAUDE.md](CLAUDE.md) for architecture details.

ign8saas-0.1.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "ign8saas"
+version = "0.1.1"
+description = "Ignite a multi-tenant SaaS control plane (Vaultwarden + wg-portal) fronted by Caddy on Hetzner Cloud."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "hcloud>=2",
+    "cloudflare>=3",
+    "paramiko>=3",
+    "pydantic>=2",
+    "pydantic-settings>=2",
+    "cryptography>=42",
+]
+
+[project.scripts]
+ign8saas = "ign8saas.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.poetry]
+packages = [{include = "ign8saas", from = "src"}]
+
+[tool.ruff]
+src = ["src"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ign8saas-0.1.1/src/ign8saas/__init__.py

@@ -0,0 +1 @@
+"""ign8saas — multi-tenant SaaS control plane provisioner."""

ign8saas-0.1.1/src/ign8saas/cli.py

@@ -0,0 +1,179 @@
+"""CLI entry point: `ign8saas up` provisions the shared SaaS control plane."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from ign8saas.config import Config
+from ign8saas.dns.cloudflare import CloudflareDNS
+from ign8saas.infra import hetzner
+from ign8saas.keys import save_keypair
+from ign8saas.saas.setup import SaaSSetup
+
+app = typer.Typer(
+    name="ign8saas",
+    help="Ignite a multi-tenant SaaS control plane (Vaultwarden + wg-portal).",
+    invoke_without_command=True,
+)
+console = Console()
+
+_STATE_DIR = Path(".ign8saas")
+_KEYS_DIR = _STATE_DIR / "keys"
+_STATE_FILE = _STATE_DIR / "state.json"
+_INIT_FILE = _STATE_DIR / "vaultwarden-init.json"
+
+
+@app.callback(invoke_without_command=True)
+def _main(
+    ctx: typer.Context,
+    env_file: Path = typer.Option(Path(".env"), "--env-file", hidden=True),
+) -> None:
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            os.environ.setdefault(k.strip(), v.strip())
+    if ctx.invoked_subcommand is None:
+        _print_status()
+
+
+@app.command()
+def up(
+    domain: str = typer.Option("traeck.it", envvar="IGN8_DOMAIN"),
+    admin_email: str = typer.Option(..., envvar="IGN8_ADMIN_EMAIL"),
+    hetzner_token: str = typer.Option(..., envvar="IGN8_HETZNER_TOKEN"),
+    hetzner_server_type: str = typer.Option("cax11", envvar="IGN8_HETZNER_SERVER_TYPE"),
+    hetzner_location: str = typer.Option("fsn1", envvar="IGN8_HETZNER_LOCATION"),
+    hetzner_image: str = typer.Option("ubuntu-24.04", envvar="IGN8_HETZNER_IMAGE"),
+    cloudflare_email: str = typer.Option(..., envvar="IGN8_CLOUDFLARE_EMAIL"),
+    cloudflare_api_key: str = typer.Option(..., envvar="IGN8_CLOUDFLARE_API_KEY"),
+    cloudflare_zone_id: str = typer.Option(..., envvar="IGN8_CLOUDFLARE_ZONE_ID"),
+    cloudflare_dns_edit_token: str = typer.Option(
+        "", envvar="IGN8_CLOUDFLARE_DNS_EDIT_TOKEN"
+    ),
+) -> None:
+    """Provision Hetzner + Cloudflare + Docker stack for the SaaS control plane."""
+    cfg = Config(
+        domain=domain,
+        admin_email=admin_email,
+        hetzner_token=hetzner_token,
+        hetzner_server_type=hetzner_server_type,
+        hetzner_location=hetzner_location,
+        hetzner_image=hetzner_image,
+        cloudflare_email=cloudflare_email,
+        cloudflare_api_key=cloudflare_api_key,
+        cloudflare_zone_id=cloudflare_zone_id,
+        cloudflare_dns_edit_token=cloudflare_dns_edit_token,
+    )
+
+    console.print("[bold green]→[/] Generating SSH keypair...")
+    priv_path, pub_path = save_keypair(_KEYS_DIR)
+    public_key = pub_path.read_text().strip()
+
+    console.print("[bold green]→[/] Provisioning Hetzner server...")
+    ips = hetzner.provision(cfg, public_key, _STATE_FILE)
+    ipv4 = ips["ipv4"]
+    console.print(f"  Server IP: [cyan]{ipv4}[/]")
+
+    console.print("[bold green]→[/] Creating Cloudflare DNS records...")
+    dns = CloudflareDNS(
+        cfg.cloudflare_email, cfg.cloudflare_api_key, cfg.cloudflare_zone_id, cfg.domain
+    )
+    dns.provision(ipv4)
+    for label in ("saas", "*.vaultwarden", "*.vpn"):
+        console.print(f"  [dim]A[/] {label}.{cfg.domain} → [cyan]{ipv4}[/]")
+
+    console.print("[bold green]→[/] Connecting to server and installing SaaS stack...")
+    setup = SaaSSetup(cfg, ipv4, priv_path).connect()
+    try:
+        creds = setup.run()
+    finally:
+        setup.disconnect()
+
+    _INIT_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _INIT_FILE.write_text(json.dumps(creds, indent=2))
+    _INIT_FILE.chmod(0o600)
+
+    console.print(
+        Panel(
+            f"[bold]Landing:[/]     https://saas.{cfg.domain}\n"
+            f"[bold]Vaultwarden:[/] https://vaultwarden.{cfg.domain}\n"
+            f"[bold]wg-portal:[/]   https://vpn.{cfg.domain}\n\n"
+            f"Credentials saved to [cyan]{_INIT_FILE}[/] (chmod 600).\n"
+            "Certificates may take a minute to issue via Cloudflare DNS-01.",
+            title="[green]SaaS control plane ready[/]",
+        )
+    )
+
+
+@app.command()
+def destroy(
+    hetzner_token: str = typer.Option(..., envvar="IGN8_HETZNER_TOKEN"),
+    cloudflare_email: str = typer.Option(..., envvar="IGN8_CLOUDFLARE_EMAIL"),
+    cloudflare_api_key: str = typer.Option(..., envvar="IGN8_CLOUDFLARE_API_KEY"),
+    cloudflare_zone_id: str = typer.Option(..., envvar="IGN8_CLOUDFLARE_ZONE_ID"),
+    domain: str = typer.Option("traeck.it", envvar="IGN8_DOMAIN"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """(TODO) Destroy the Hetzner server and remove DNS records."""
+    raise NotImplementedError(
+        "destroy is not implemented yet; delete the Hetzner server and Cloudflare"
+        " records manually for now."
+    )
+
+
+@app.command(name="add-customer")
+def add_customer(
+    slug: str = typer.Argument(..., help="Customer slug (used as vanity subdomain)"),
+    email: str = typer.Option(..., "--email", help="Customer email address"),
+) -> None:
+    """(TODO) Onboard a new customer (Vaultwarden invite + wg-portal peer)."""
+    raise NotImplementedError(
+        "add-customer is not implemented yet; use the Vaultwarden admin UI and"
+        " wg-portal admin UI directly for now."
+    )
+
+
+@app.command(name="del-customer")
+def del_customer(
+    slug: str = typer.Argument(..., help="Customer slug to remove"),
+) -> None:
+    """(TODO) Off-board a customer (revoke vault user + delete wg peer)."""
+    raise NotImplementedError(
+        "del-customer is not implemented yet; use the Vaultwarden admin UI and"
+        " wg-portal admin UI directly for now."
+    )
+
+
+def _load_state() -> dict[str, Any]:
+    if not _STATE_FILE.exists():
+        console.print("[red]No state found. Run `ign8saas up` first.[/]")
+        raise typer.Exit(1)
+    return json.loads(_STATE_FILE.read_text())  # type: ignore[no-any-return]
+
+
+def _print_status() -> None:
+    if _STATE_FILE.exists():
+        state = json.loads(_STATE_FILE.read_text())
+        console.print(
+            Panel(
+                f"[bold]Server:[/] {state.get('ipv4', '?')}\n"
+                f"[bold]Domain:[/] {state.get('domain', '?')}\n"
+                f"[bold]Customers:[/] {len(state.get('customers') or {})}",
+                title="ign8saas status",
+            )
+        )
+    else:
+        console.print(
+            Panel(
+                "No SaaS control plane provisioned. Run [cyan]ign8saas up[/] to get started.",
+                title="ign8saas",
+            )
+        )

ign8saas-0.1.1/src/ign8saas/config.py

@@ -0,0 +1,33 @@
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="IGN8_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    # Required — parent domain (three records are created underneath it)
+    domain: str = "traeck.it"
+    admin_email: str
+
+    # Hetzner Cloud
+    hetzner_token: str
+    hetzner_server_type: str = "cax11"
+    hetzner_location: str = "fsn1"
+    hetzner_image: str = "ubuntu-24.04"
+
+    # Cloudflare (Global API Key auth — scoped tokens don't cover traeck.it)
+    cloudflare_email: str
+    cloudflare_api_key: str
+    cloudflare_zone_id: str
+
+    # Separate scoped token with Zone/DNS Edit for Caddy's DNS-01 challenge
+    cloudflare_dns_edit_token: str = ""
+
+    @field_validator("domain")
+    @classmethod
+    def strip_trailing_dot(cls, v: str) -> str:
+        return v.rstrip(".")

ign8saas-0.1.1/src/ign8saas/dns/cloudflare.py

@@ -0,0 +1,55 @@
+"""Create DNS A records for the SaaS control plane in the parent zone.
+
+Three records are managed idempotently:
+  - saas.<domain>            → ipv4
+  - *.vaultwarden.<domain>   → ipv4
+  - *.vpn.<domain>           → ipv4
+
+Uses the Cloudflare Global API Key (X-Auth-Email + X-Auth-Key) because our
+default scoped tokens don't cover the traeck.it zone.
+"""
+
+from typing import Any
+
+import cloudflare
+
+
+class CloudflareDNS:
+    def __init__(self, email: str, api_key: str, zone_id: str, domain: str) -> None:
+        # Global API Key auth. cloudflare-python accepts (api_email, api_key).
+        self._cf = cloudflare.Cloudflare(api_email=email, api_key=api_key)
+        self._zone = zone_id
+        self._domain = domain
+
+    def _record_names(self) -> list[str]:
+        d = self._domain
+        return [f"saas.{d}", f"*.vaultwarden.{d}", f"*.vpn.{d}"]
+
+    def provision(self, ipv4: str) -> None:
+        targets = self._record_names()
+        existing_by_name: dict[str, Any] = {}
+        for existing in self._cf.dns.records.list(zone_id=self._zone).result or []:
+            if existing.name in targets:
+                # Keep the last one seen — duplicates are removed on update below.
+                existing_by_name.setdefault(existing.name, existing)
+
+        for name in targets:
+            payload: dict[str, Any] = {
+                "type": "A",
+                "name": name,
+                "content": ipv4,
+                "proxied": False,
+                "ttl": 1,
+            }
+            if name in existing_by_name:
+                self._cf.dns.records.update(
+                    existing_by_name[name].id, zone_id=self._zone, **payload
+                )
+            else:
+                self._cf.dns.records.create(zone_id=self._zone, **payload)
+
+    def destroy(self) -> None:
+        targets = set(self._record_names())
+        for existing in self._cf.dns.records.list(zone_id=self._zone).result or []:
+            if existing.name in targets:
+                self._cf.dns.records.delete(existing.id, zone_id=self._zone)

ign8saas-0.1.1/src/ign8saas/infra/hetzner.py

@@ -0,0 +1,116 @@
+"""Hetzner Cloud provisioner: SSH key, firewall, and server via the hcloud SDK."""
+
+import ipaddress
+import json
+from pathlib import Path
+from typing import Any
+
+from hcloud import Client
+from hcloud.firewalls.domain import FirewallRule
+from hcloud.images import Image
+from hcloud.locations import Location
+from hcloud.server_types import ServerType
+
+from ign8saas.config import Config
+
+_SSH_KEY_NAME = "ign8saas-key"
+_FW_NAME = "ign8saas-fw"
+
+
+def _server_name(domain: str) -> str:
+    """`saas-<first-label>`; e.g. traeck.it → saas-traeck."""
+    first = (domain.split(".") or ["default"])[0] or "default"
+    return f"saas-{first}"
+
+
+def provision(cfg: Config, public_key: str, state_path: Path) -> dict[str, str]:
+    client = Client(token=cfg.hetzner_token)
+
+    ssh_key = _ensure_ssh_key(client, public_key)
+    firewall = _ensure_firewall(client)
+    server = _ensure_server(client, cfg, ssh_key, firewall)
+
+    ipv4 = server.public_net.ipv4.ip if server.public_net.ipv4 else ""
+    ipv6 = ""
+    if server.public_net.ipv6:
+        net = ipaddress.IPv6Network(server.public_net.ipv6.ip)
+        ipv6 = str(net.network_address + 1)
+
+    hostname = f"saas.{cfg.domain}"
+    if ipv4:
+        server.change_dns_ptr(ip=ipv4, dns_ptr=hostname).wait_until_finished()
+
+    state: dict[str, object] = {
+        "server_id": server.id,
+        "server_name": _server_name(cfg.domain),
+        "ssh_key_id": ssh_key.id,
+        "firewall_id": firewall.id,
+        "ipv4": ipv4,
+        "ipv6": ipv6,
+        "domain": cfg.domain,
+        "customers": {},
+    }
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    state_path.write_text(json.dumps(state, indent=2))
+
+    return {"ipv4": ipv4, "ipv6": ipv6}
+
+
+def destroy(state_path: Path, hetzner_token: str, domain: str) -> None:
+    client = Client(token=hetzner_token)
+    name = _server_name(domain)
+
+    for server in client.servers.get_all(name=name):
+        server.delete().wait_until_finished()
+
+    for fw in client.firewalls.get_all(name=_FW_NAME):
+        fw.delete()
+
+    for key in client.ssh_keys.get_all(name=_SSH_KEY_NAME):
+        key.delete()
+
+    state_path.unlink(missing_ok=True)
+
+
+def _ensure_ssh_key(client: Client, public_key: str) -> Any:
+    existing = client.ssh_keys.get_all(name=_SSH_KEY_NAME)
+    if existing:
+        key = existing[0]
+        if (key.public_key or "").strip() != public_key.strip():
+            key.delete()
+        else:
+            return key
+    return client.ssh_keys.create(name=_SSH_KEY_NAME, public_key=public_key)
+
+
+def _ensure_firewall(client: Client) -> Any:
+    existing = client.firewalls.get_all(name=_FW_NAME)
+    if existing:
+        return existing[0]
+    rules = [
+        FirewallRule(direction="in", protocol="tcp", port="22", source_ips=["0.0.0.0/0", "::/0"]),
+        FirewallRule(direction="in", protocol="tcp", port="80", source_ips=["0.0.0.0/0", "::/0"]),
+        FirewallRule(direction="in", protocol="tcp", port="443", source_ips=["0.0.0.0/0", "::/0"]),
+        FirewallRule(
+            direction="in", protocol="udp", port="51820", source_ips=["0.0.0.0/0", "::/0"]
+        ),
+    ]
+    return client.firewalls.create(name=_FW_NAME, rules=rules).firewall
+
+
+def _ensure_server(client: Client, cfg: Config, ssh_key: Any, firewall: Any) -> Any:
+    name = _server_name(cfg.domain)
+    existing = client.servers.get_all(name=name)
+    if existing:
+        return existing[0]
+    response = client.servers.create(
+        name=name,
+        server_type=ServerType(name=cfg.hetzner_server_type),
+        image=Image(name=cfg.hetzner_image),
+        location=Location(name=cfg.hetzner_location),
+        ssh_keys=[ssh_key],
+        firewalls=[firewall],
+        labels={"managed-by": "ign8saas", "domain": cfg.domain},
+    )
+    response.action.wait_until_finished()
+    return response.server

ign8saas-0.1.1/src/ign8saas/keys.py

@@ -0,0 +1,50 @@
+import base64
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+
+
+def save_keypair(directory: Path, name: str = "ign8saas") -> tuple[Path, Path]:
+    """Generate RSA SSH keypair if absent, return (private_path, public_path)."""
+    directory.mkdir(parents=True, exist_ok=True)
+    priv_path = directory / name
+    pub_path = directory / f"{name}.pub"
+
+    if not priv_path.exists():
+        private_key = rsa.generate_private_key(public_exponent=65537, key_size=4096)
+        priv_path.write_text(
+            private_key.private_bytes(
+                serialization.Encoding.PEM,
+                serialization.PrivateFormat.OpenSSH,
+                serialization.NoEncryption(),
+            ).decode()
+        )
+        priv_path.chmod(0o600)
+        pub_path.write_text(
+            private_key.public_key().public_bytes(
+                serialization.Encoding.OpenSSH,
+                serialization.PublicFormat.OpenSSH,
+            ).decode()
+        )
+    return priv_path, pub_path
+
+
+def generate_wg_keypair() -> tuple[str, str]:
+    """Return (private_key_b64, public_key_b64) for a WireGuard peer."""
+    private_key = X25519PrivateKey.generate()
+    private_b64 = base64.b64encode(
+        private_key.private_bytes(
+            serialization.Encoding.Raw,
+            serialization.PrivateFormat.Raw,
+            serialization.NoEncryption(),
+        )
+    ).decode()
+    public_b64 = base64.b64encode(
+        private_key.public_key().public_bytes(
+            serialization.Encoding.Raw,
+            serialization.PublicFormat.Raw,
+        )
+    ).decode()
+    return private_b64, public_b64

ign8saas-0.1.1/src/ign8saas/saas/setup.py

@@ -0,0 +1,266 @@
+"""SSH into the provisioned server and install Docker + the SaaS compose stack.
+
+Deploys three containers behind Caddy:
+  - vaultwarden — Bitwarden-compatible password vault
+  - wg-portal   — WireGuard admin UI (exposes 51820/udp publicly)
+  - caddy       — TLS termination + reverse proxy + wildcard certs (DNS-01)
+"""
+
+import io
+import time
+from pathlib import Path
+from typing import Optional
+
+import paramiko  # type: ignore[import-untyped]
+
+from ign8saas.config import Config
+
+_COMPOSE_YML_TMPL = """\
+services:
+  caddy:
+    image: ghcr.io/caddybuilds/caddy-cloudflare:latest
+    restart: unless-stopped
+    ports:
+      - "0.0.0.0:80:80"
+      - "0.0.0.0:443:443"
+      - "0.0.0.0:443:443/udp"
+    environment:
+      # Scoped token when set; otherwise the plugin falls back to the
+      # Global API Key (email + key) form written into the Caddyfile.
+      CLOUDFLARE_API_TOKEN: "{cloudflare_dns_edit_token}"
+      CLOUDFLARE_EMAIL: "{cloudflare_email}"
+      CLOUDFLARE_API_KEY: "{cloudflare_api_key}"
+      ACME_EMAIL: "{admin_email}"
+    volumes:
+      - /opt/saas/Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - vaultwarden
+      - wg-portal
+
+  vaultwarden:
+    image: vaultwarden/server:latest
+    restart: unless-stopped
+    environment:
+      DOMAIN: "https://vaultwarden.{domain}"
+      SIGNUPS_ALLOWED: "false"
+      INVITATIONS_ALLOWED: "true"
+      ADMIN_TOKEN: "{vaultwarden_admin_token}"
+    volumes:
+      - vaultwarden_data:/data
+    ports:
+      - "127.0.0.1:11080:80"
+
+  wg-portal:
+    image: ghcr.io/h44z/wg-portal:latest
+    restart: unless-stopped
+    cap_add:
+      - NET_ADMIN
+    environment:
+      WG_PORTAL_ADMIN_USER: "{wg_portal_admin_user}"
+      WG_PORTAL_ADMIN_PASSWORD: "{wg_portal_admin_password}"
+      EXTERNAL_URL: "https://vpn.{domain}"
+    volumes:
+      - wgportal_data:/app/data
+      - wgportal_config:/app/config
+    ports:
+      - "127.0.0.1:11081:8888"
+      - "51820:51820/udp"
+
+volumes:
+  caddy_data:
+  caddy_config:
+  vaultwarden_data:
+  wgportal_data:
+  wgportal_config:
+"""
+
+# Caddy config. The vanity-slug matcher on `*.vaultwarden.<domain>` redirects to
+# the canonical vault so a link like `alice-at-example-com.vaultwarden.<domain>`
+# opens the login page with the email prefilled.
+_CADDYFILE_TMPL = """\
+{{
+    email {admin_email}
+}}
+
+saas.{domain} {{
+    respond "SaaS control plane — coming soon" 200
+    tls {{
+        {dns_auth}
+    }}
+}}
+
+vaultwarden.{domain}, *.vaultwarden.{domain} {{
+    tls {{
+        {dns_auth}
+    }}
+
+    @vanity host_regexp vanity ^(?P<slug>(?!vaultwarden$)[^.]+)\\.vaultwarden\\.{domain_re}$
+    redir @vanity https://vaultwarden.{domain}/#/login?email={{re.vanity.slug}} 302
+
+    reverse_proxy vaultwarden:80
+}}
+
+vpn.{domain}, *.vpn.{domain} {{
+    tls {{
+        {dns_auth}
+    }}
+    reverse_proxy wg-portal:8888
+}}
+"""
+
+
+class SaaSSetup:
+    def __init__(self, cfg: Config, host: str, private_key_path: Path) -> None:
+        self._cfg = cfg
+        self._host = host
+        self._key_path = str(private_key_path)
+        self._ssh: Optional[paramiko.SSHClient] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+
+    def connect(self, retries: int = 30, delay: int = 10) -> "SaaSSetup":
+        """Retry SSH for up to ~5 minutes while cloud-init finishes booting."""
+        client = paramiko.SSHClient()
+        client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+        key = paramiko.RSAKey.from_private_key_file(self._key_path)
+        for attempt in range(retries):
+            try:
+                client.connect(self._host, username="root", pkey=key, timeout=15)
+                self._ssh = client
+                return self
+            except Exception:
+                if attempt == retries - 1:
+                    raise
+                time.sleep(delay)
+        return self
+
+    def disconnect(self) -> None:
+        if self._ssh:
+            self._ssh.close()
+            self._ssh = None
+
+    def run(self) -> dict[str, str]:
+        """Install stack; return generated credentials for cli.py to persist."""
+        assert self._ssh, "Call connect() first"
+
+        self._install_base_packages()
+        self._install_docker()
+
+        vaultwarden_admin_token = self._rand_token(48)
+        wg_portal_admin_user = "admin"
+        wg_portal_admin_password = self._rand_token(24)
+
+        self._write_stack(
+            vaultwarden_admin_token=vaultwarden_admin_token,
+            wg_portal_admin_user=wg_portal_admin_user,
+            wg_portal_admin_password=wg_portal_admin_password,
+        )
+        self._compose_up()
+        self._wait_for_vaultwarden()
+
+        return {
+            "vaultwarden_admin_token": vaultwarden_admin_token,
+            "wg_portal_admin_user": wg_portal_admin_user,
+            "wg_portal_admin_password": wg_portal_admin_password,
+        }
+
+    # ------------------------------------------------------------------
+    # Steps
+
+    def _install_base_packages(self) -> None:
+        self._exec("apt-get update -qq")
+        self._exec(
+            "DEBIAN_FRONTEND=noninteractive apt-get install -y -qq"
+            " ca-certificates curl gnupg"
+        )
+
+    def _install_docker(self) -> None:
+        already = self._exec("command -v docker >/dev/null 2>&1 && echo yes || echo no").strip()
+        if already != "yes":
+            # Official convenience script — installs engine + compose plugin.
+            self._exec("curl -fsSL https://get.docker.com | sh")
+        self._exec("systemctl enable --now docker")
+
+    def _write_stack(
+        self,
+        vaultwarden_admin_token: str,
+        wg_portal_admin_user: str,
+        wg_portal_admin_password: str,
+    ) -> None:
+        self._exec("mkdir -p /opt/saas")
+
+        compose = _COMPOSE_YML_TMPL.format(
+            domain=self._cfg.domain,
+            admin_email=self._cfg.admin_email,
+            cloudflare_dns_edit_token=self._cfg.cloudflare_dns_edit_token,
+            cloudflare_email=self._cfg.cloudflare_email,
+            cloudflare_api_key=self._cfg.cloudflare_api_key,
+            vaultwarden_admin_token=vaultwarden_admin_token,
+            wg_portal_admin_user=wg_portal_admin_user,
+            wg_portal_admin_password=wg_portal_admin_password,
+        )
+        self._write_remote("/opt/saas/docker-compose.yml", compose)
+        self._exec("chmod 600 /opt/saas/docker-compose.yml")
+
+        # Escape the domain for use inside a Caddy regex (dots become literal).
+        domain_re = self._cfg.domain.replace(".", r"\.")
+        # Pick the DNS-01 auth form: scoped token if configured, else the
+        # Global API Key fallback the plugin also accepts.
+        if self._cfg.cloudflare_dns_edit_token:
+            dns_auth = "dns cloudflare {env.CLOUDFLARE_API_TOKEN}"
+        else:
+            dns_auth = "dns cloudflare {env.CLOUDFLARE_EMAIL} {env.CLOUDFLARE_API_KEY}"
+        caddyfile = _CADDYFILE_TMPL.format(
+            domain=self._cfg.domain,
+            domain_re=domain_re,
+            admin_email=self._cfg.admin_email,
+            dns_auth=dns_auth,
+        )
+        self._write_remote("/opt/saas/Caddyfile", caddyfile)
+
+    def _compose_up(self) -> None:
+        self._exec("cd /opt/saas && docker compose pull")
+        self._exec("cd /opt/saas && docker compose up -d")
+
+    def _wait_for_vaultwarden(self, timeout_s: int = 60) -> None:
+        deadline = time.time() + timeout_s
+        last: str = ""
+        while time.time() < deadline:
+            last = self._exec(
+                "curl -s -o /dev/null -w '%{http_code}'"
+                " http://127.0.0.1:11080/alive || true"
+            ).strip()
+            if last == "200":
+                return
+            time.sleep(3)
+        raise RuntimeError(
+            f"Vaultwarden /alive did not return 200 within {timeout_s}s (last: {last!r})"
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+
+    def _rand_token(self, byte_len: int) -> str:
+        # Generated on the server to avoid dragging OpenSSL requirements into the
+        # local process; matches the spec ("openssl rand -base64 48").
+        return self._exec(f"openssl rand -base64 {byte_len}").strip()
+
+    def _write_remote(self, remote_path: str, content: str) -> None:
+        assert self._ssh
+        sftp = self._ssh.open_sftp()
+        try:
+            sftp.putfo(io.BytesIO(content.encode()), remote_path)
+        finally:
+            sftp.close()
+
+    def _exec(self, cmd: str) -> str:
+        assert self._ssh
+        _, stdout, stderr = self._ssh.exec_command(cmd)
+        exit_code = stdout.channel.recv_exit_status()
+        output: str = stdout.read().decode()
+        if exit_code != 0:
+            raise RuntimeError(f"Command failed ({exit_code}): {cmd}\n{stderr.read().decode()}")
+        return output