# Cross-project notification — Standards v2.7

> **Audience:** every Magogi web-service consumer maintainer.
> **TL;DR:** new standard [`DEPLOYMENT.md`](../standards/DEPLOYMENT.md)
> with eleven MUSTs (DEP-01..DEP-11) covering how stateful web
> services get deployed to the cloud. Cloud-agnostic; Infomaniak
> is the foundation's main reference platform. Most projects
> will land at "audit needed" — none of these rules are new
> ideas, but they're now written down. Per-shape action lists
> at the bottom.

---

## What's new

`mgf-common/docs/standards/DEPLOYMENT.md` adds eleven MUSTs that
describe how a stateful web service goes from a git tag to a
running production environment. The rules are extracted from
two real reference deployments:

- **[`django-infomaniak-deploy`](https://codeberg.org/magogi-admin/django-infomaniak-deploy)** —
  the reusable framework. Clone-as-starting-point for new
  Django/FastAPI consumers; produces the canonical layout via
  `setup.sh`.
- **[`inthewords/deploy`](https://codeberg.org/magogi-admin/inthewords/src/branch/main/deploy)** —
  first end-to-end consumer of the framework. Validates the
  whole pattern on Infomaniak.

The eleven rules in summary:

| ID | Rule (one-line) |
|---|---|
| **DEP-01** | Cloud infra MUST be Infrastructure-as-Code (Terraform / Pulumi / OpenTofu / CDK). |
| **DEP-02** | VM state MUST be Configuration-as-Code (Ansible / Chef / Salt / cloud-init). |
| **DEP-03** | Release artefacts MUST be immutable. Dependencies locked at build time. |
| **DEP-04** | Production secrets MUST live outside the repo, encrypted at rest. |
| **DEP-05** | Deploy / backup / restore / rollback scripts MUST take an environment arg; refuse bare invocation. |
| **DEP-06** | Deploys MUST be reversible with a documented ≤5-minute rollback. |
| **DEP-07** | The `deploy/` directory MUST follow the canonical shape (README + IaC + config-mgmt + scripts + monitoring + docs). |
| **DEP-08** | Production MUST be observable end-to-end; SLO file + burn-rate alerts + runbook-linked alerts. |
| **DEP-09** | DNS MUST be in IaC or committed; TLS MUST auto-renew. |
| **DEP-10** | `first-production-cut.md` runbook MUST document green-field provisioning. |
| **DEP-11** | Deployable to ≥2 environments (prod + staging/dev) from the same code. |

Full rules + per-rule rationale + reference shapes:
[`DEPLOYMENT.md`](../standards/DEPLOYMENT.md).

---

## Who this applies to

DEP-* applies to **stateful web-service consumer applications**.

| Project type | DEP-* applies? |
|---|---|
| **Cornerstone library** (`mgf-common`) | ❌ — no runtime to deploy |
| **Federation siblings** (`mgf-django`, `mgf-fastapi`, etc.) | ❌ — no runtime to deploy; the libraries ship to PyPI |
| **Consumer web service** (`inthewords`, `PlasmaMapper`, future SaaS) | ✅ — full DEP-01..DEP-11 |
| **Consumer desktop app** (`VManager`) | ❌ — distributed as binaries, not deployed |
| **Static website** (`magogi-website`) | ⚠️ subset — DEPLOYMENT.md §8.2 has the static-site-shape rules (DEP-01, 03, 04, 05, 06, 07-simplified, 09, 10, 11) |

---

## Cloud-agnostic — Infomaniak first

The standard is **cloud-agnostic**: the rules describe WHAT
must be true, the HOW is tool-agnostic. But the Magogi
foundation's main reference platform is **Infomaniak Public
Cloud** (Swiss-hosted, OpenStack-based), and `DEPLOYMENT.md`
§8.1 carries the deepest content for it:

- The Infomaniak service catalogue (compute, LB, networking,
  object storage, email, …) with prices.
- The gaps and workarounds (no managed PostgreSQL → self-hosted
  on a VM; no first-party CDN → Cloudflare; no managed Redis →
  self-hosted on a VM).
- The reference architecture (multi-VM with private network +
  Octavia LB + Cloudflare edge).
- The OpenStack auth quirks (application credentials vs Object
  Storage access keys).

§8.3 covers AWS / Azure / GCP shape-translation pointers
(RDS / ElastiCache / S3 / etc.).

§8.4 covers managed-platform shapes (Fly.io / Render /
Heroku / Vercel) where some rules collapse because the
platform owns the VM.

---

## How DEPLOYMENT.md relates to OPERABILITY.md

These two standards are **complementary**:

- **DEPLOYMENT.md** covers infra + CI/CD — "how do you get
  bits onto servers."
- **OPERABILITY.md** covers runtime ops — "how do you run
  them once they're there."

The cross-links at the natural seams:

| OPERABILITY rule | DEPLOYMENT side |
|---|---|
| OP-10 (versioned artefacts, rollback exercised) | DEP-06 (reversible deploys ≤5min, drill-tested) |
| OP-11 (alerts page humans, runbook_url per alert) | DEP-08 (observability sink + alert wiring) |
| OP-12 (backup-restore drill against real target) | DEP-08 (monitoring) + DEP-04 (secrets to restore credentials safely) |

No content overlaps; the boundary is clean.

---

## Per-project action lists

Based on the audit run on 2026-05-15.

### `inthewords` (Django web — Infomaniak)

✅ Already the reference shape for DEP-01..DEP-11. The
`inthewords/deploy/` tree is what §3 of the new standard
codifies. **Nothing to do** for v2.7 compliance.

Optional improvements (not required for v2.7):
- ℹ The deploy currently uses pip-tools lock files; a
  future migration to `uv.lock` would align with mgf-common.
- ℹ The first-production-cut runbook predates the standard;
  on next deploy-touching PR, refresh it against §4.10.

### `PlasmaMapper` (FastAPI SaaS — Infomaniak)

The project ships to Infomaniak; the FastAPI shape is
documented in `docs/standards/MULTI_TENANCY.md`. v2.7
audit items:

- ⚠ Verify `deploy/` directory shape matches §3 — most
  likely needs a `monitoring/` + `docs/runbook.md` +
  `docs/slo.md` if not already present.
- ⚠ Confirm DEP-04: are all secrets in Ansible Vault or
  cloud KMS? Any `.env`-style production credentials need
  migration.
- ⚠ Confirm DEP-06: documented rollback procedure with
  a ≤5-minute time bound. The PAPER-27 IP-allowlist work
  introduced some prod-only paths — ensure they're
  rollback-safe.
- ⚠ Confirm DEP-11: prod + staging deployable from same
  code. Multi-tenant + RLS shape can trip the
  same-code-two-envs rule if staging schemas drift.

### `magogi-website` (static site)

Static-site shape per §8.2. v2.7 audit items:

- ⚠ Confirm DEP-01: is the Object Storage bucket + CDN +
  DNS in Terraform / equivalent? Or is the site uploaded
  ad-hoc?
- ⚠ Confirm DEP-05: is there a `publish.sh prod` script
  that takes an explicit env arg?
- ⚠ Confirm DEP-06: does Object Storage versioning enable
  a previous-objects rollback? If not, enable it.
- ⚠ Add `deploy/docs/runbook.md` — even a thin one
  covering "site is down: check DNS / CDN / bucket".
- ℹ DEP-02 (config-as-code) is N/A — no VM.

### Federation siblings (`mgf-django`, `mgf-fastapi`, `mgf-http`, `mgf-sqlalchemy`, `mgf-alembic`, `mgf-apiprobe`, `mgf-website-template`)

❌ DEP-* does NOT apply — these libraries ship to PyPI; they
don't have runtime to deploy. **Nothing to do.**

### Desktop apps (`VManager`)

❌ DEP-* does NOT apply — distributed as binaries / packages,
not deployed to cloud infrastructure. **Nothing to do** for
this standard. (VManager's `bundle`, `update-check`, and
similar concerns belong in OPERABILITY.md / RELEASING.md.)

### Future projects

When a new web-service consumer is bootstrapped, the
recommended path:

1. Clone [`django-infomaniak-deploy`](https://codeberg.org/magogi-admin/django-infomaniak-deploy)
   as the deploy/ scaffolding.
2. Run `bash setup.sh` to substitute project / domain /
   repo placeholders.
3. Walk the `phase-1` through `phase-5` docs in order.
4. Run the first-production-cut drill against a staging
   environment.
5. Cut over.

The framework realises DEP-01..DEP-11 by construction; no
project that follows the framework needs to re-derive the
rules.

---

## What this does NOT change

- **No existing deploy is broken.** v2.7 is additive — new
  MUSTs that codify discipline existing reference deploys
  already follow.
- **No CI gates change.** Doc-only.
- **No code changes.** Standards work; not code.
- **No urgency.** Roll the audit items in at your next
  deploy-touching PR.

---

## Reference

- New standard: [`mgf-common/docs/standards/DEPLOYMENT.md`](../standards/DEPLOYMENT.md)
- v2.7 release notes: [`mgf-common/docs/standards/README.md`](../standards/README.md) "What's new in v2.7"
- Reference framework: [`django-infomaniak-deploy`](https://codeberg.org/magogi-admin/django-infomaniak-deploy)
- Reference consumer: [`inthewords/deploy`](https://codeberg.org/magogi-admin/inthewords/src/branch/main/deploy)
- Companion runtime standard: [`OPERABILITY.md`](../standards/OPERABILITY.md)

Questions? File a FEEDBACK paper at
[`mgf-common/FEEDBACK.md`](../../FEEDBACK.md) or open an issue
on the mgf-common Codeberg.
