julien/apf_portal
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(infra): document team mkcert CA on vm-gitlab (cross-VM trust) #264

Merged
julien merged 1 commits from docs/team-mkcert-ca into main 2026-06-01 23:30:56 +02:00
Conversation 0 Commits 1 Files Changed 1
+111
julien commented 2026-06-01 23:30:37 +02:00
Owner
Copy Link
Copy Source

Summary

Doc-only follow-up to the just-shipped ADR-0030 dockerised dev mode + dev-server TLS (PR #263). Adds a "Team mkcert CA on vm-gitlab" subsection to infra/README.md so a teammate joining the project can browse any dev VM with a green padlock (cross-VM access) without each pair of devs having to swap their private CAs.

Hits a real need: a third developer is about to onboard, and the current single-dev mkcert procedure doesn't scale beyond one — each dev's solo CA is only trusted by their own workstation, so colleagues hitting another VM see a NET::ERR_CERT_AUTHORITY_INVALID warning every time.

What lands

infra/README.md — one new subsection added immediately after the existing "HTTPS dev-server setup" block, under the same Local-dev-stack section. No other file touched.

The subsection documents:

  1. Initial setup on vm-gitlab — install mkcert, create a root-only CAROOT at /srv/apf-portal/mkcert-ca/, generate the team CA there. Run once by the R&D Lead.
  2. Minting per-VM certs — the canonical mkcert -key-file … -cert-file … apf-portal.<host>.local invocation pointed at the shared CAROOT, plus a sanity openssl x509 -subject -issuer step and the scp to the target VM's ~/Works/apf_portal/.secrets/dev-tls.{key,pem}.
  3. Onboarding a new developer — what flows where:
    • R&D Lead → new dev: rootCA.pem (public cert, secure channel — 1Password / Bitwarden / direct scp, never plain e-mail) + the per-VM cert pair already on their VM.
    • New dev's workstation: drop rootCA.pem into the local mkcert -CAROOT, run mkcert -install to push the team CA into the Windows trust store.
    • Standard hosts / .env / NX_SERVE_CONFIGURATION=https / dev.sh up apps follow.
  4. Operational notes — departures (no CRL needed because the dev never held the private key), CA rotation, per-VM cert rotation, future migration to a corp-CA-signed cert.

Why vm-gitlab as the CA host

The CA itself is just two files (rootCA.pem + rootCA-key.pem); it does not need a service running. vm-gitlab is the natural home for a few reasons:

  • It is already a shared, team-managed infra VM, owned by the same person who would mint the certs anyway.
  • The CA outlives any individual dev's laptop or workstation reinstall.
  • Restricting the directory to root keeps the private key out of every developer's blast radius — only the R&D Lead with sudo on vm-gitlab can mint.

The R&D Lead becomes the steward; developers never need SSH access to vm-gitlab. That trade — slight bottleneck at onboarding for much smaller key-exposure surface — is the right balance at small team scale.

Why not just distribute the CA key

Considered the alternative — every dev gets both rootCA.pem and rootCA-key.pem in their local mkcert CAROOT so they can mint their own certs. Pros: no bottleneck. Cons: the CA private key would live on N workstations, and anyone with it can forge a trusted cert for any hostname on any teammate's machine. Acceptable at 2 devs of complete trust; risky at 3+. The steward pattern scales without that trade.

Test plan

  • Doc renders cleanly in the infra/README.md flow (subsection lands between "HTTPS dev-server setup" and "Service endpoints (defaults)").
  • R&D Lead walks the "Initial setup on vm-gitlab" steps and confirms the CA files end up at /srv/apf-portal/mkcert-ca/ with the documented permissions.
  • First new-dev onboarding (the upcoming third dev) follows the section end-to-end and reaches https://apf-portal.dev-<their>.local:4200/ with a green padlock.
  • Verify the "browse from one dev's workstation to another dev's VM" promise: after the team CA is installed on at least two workstations, both can browse https://apf-portal.dev-jg.local:4200/ and https://apf-portal.dev-vc.local:4200/ without a cert warning.

Related

  • ADR-0030 — the dockerised dev mode this completes for team-scale operation.
  • ADR-0028 — places vm-gitlab as shared infra; this PR uses it as the natural CA host.
  • PR #263 (feat(spa): opt-in 'https' nx serve config for dev-server TLS) — provides the dev-server TLS plumbing this section instructs how to feed.
## Summary Doc-only follow-up to the just-shipped ADR-0030 dockerised dev mode + dev-server TLS (PR #263). Adds a "Team mkcert CA on `vm-gitlab`" subsection to `infra/README.md` so a teammate joining the project can browse any dev VM with a green padlock (cross-VM access) without each pair of devs having to swap their private CAs. Hits a real need: a third developer is about to onboard, and the current single-dev mkcert procedure doesn't scale beyond one — each dev's solo CA is only trusted by their own workstation, so colleagues hitting another VM see a `NET::ERR_CERT_AUTHORITY_INVALID` warning every time. ## What lands `infra/README.md` — one new subsection added immediately after the existing "HTTPS dev-server setup" block, under the same Local-dev-stack section. No other file touched. The subsection documents: 1. **Initial setup on `vm-gitlab`** — install mkcert, create a root-only `CAROOT` at `/srv/apf-portal/mkcert-ca/`, generate the team CA there. Run once by the R&D Lead. 2. **Minting per-VM certs** — the canonical `mkcert -key-file … -cert-file … apf-portal.<host>.local` invocation pointed at the shared `CAROOT`, plus a sanity `openssl x509 -subject -issuer` step and the `scp` to the target VM's `~/Works/apf_portal/.secrets/dev-tls.{key,pem}`. 3. **Onboarding a new developer** — what flows where: - R&D Lead → new dev: `rootCA.pem` (public cert, secure channel — 1Password / Bitwarden / direct scp, never plain e-mail) + the per-VM cert pair already on their VM. - New dev's workstation: drop `rootCA.pem` into the local `mkcert -CAROOT`, run `mkcert -install` to push the team CA into the Windows trust store. - Standard `hosts` / `.env` / `NX_SERVE_CONFIGURATION=https` / `dev.sh up apps` follow. 4. **Operational notes** — departures (no CRL needed because the dev never held the private key), CA rotation, per-VM cert rotation, future migration to a corp-CA-signed cert. ## Why `vm-gitlab` as the CA host The CA itself is just two files (`rootCA.pem` + `rootCA-key.pem`); it does not need a service running. `vm-gitlab` is the natural home for a few reasons: - It is already a **shared, team-managed infra VM**, owned by the same person who would mint the certs anyway. - The CA outlives any individual dev's laptop or workstation reinstall. - Restricting the directory to `root` keeps the private key out of every developer's blast radius — only the R&D Lead with `sudo` on `vm-gitlab` can mint. The R&D Lead becomes the steward; developers never need SSH access to `vm-gitlab`. That trade — slight bottleneck at onboarding for much smaller key-exposure surface — is the right balance at small team scale. ## Why not just distribute the CA key Considered the alternative — every dev gets both `rootCA.pem` and `rootCA-key.pem` in their local mkcert `CAROOT` so they can mint their own certs. Pros: no bottleneck. Cons: the CA private key would live on N workstations, and anyone with it can forge a trusted cert for any hostname on any teammate's machine. Acceptable at 2 devs of complete trust; risky at 3+. The steward pattern scales without that trade. ## Test plan - [x] Doc renders cleanly in the `infra/README.md` flow (subsection lands between "HTTPS dev-server setup" and "Service endpoints (defaults)"). - [ ] R&D Lead walks the "Initial setup on `vm-gitlab`" steps and confirms the CA files end up at `/srv/apf-portal/mkcert-ca/` with the documented permissions. - [ ] First new-dev onboarding (the upcoming third dev) follows the section end-to-end and reaches `https://apf-portal.dev-<their>.local:4200/` with a green padlock. - [ ] Verify the "browse from one dev's workstation to another dev's VM" promise: after the team CA is installed on at least two workstations, both can browse `https://apf-portal.dev-jg.local:4200/` and `https://apf-portal.dev-vc.local:4200/` without a cert warning. ## Related - [ADR-0030](docs/decisions/0030-dockerised-dev-mode.md) — the dockerised dev mode this completes for team-scale operation. - [ADR-0028](docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md) — places `vm-gitlab` as shared infra; this PR uses it as the natural CA host. - PR #263 (`feat(spa): opt-in 'https' nx serve config for dev-server TLS`) — provides the dev-server TLS plumbing this section instructs how to feed.
julien added 1 commit 2026-06-01 23:30:37 +02:00
docs(infra): document team mkcert CA on vm-gitlab (cross-VM trust)
CI / scan (pull_request) Failing after 2m32s
Details
CI / commits (pull_request) Successful in 2m32s
Details
CI / check (pull_request) Successful in 2m45s
Details
CI / a11y (pull_request) Successful in 2m10s
Details
CI / perf (pull_request) Successful in 5m37s
Details
ad44c5b15d 
Add a Team mkcert CA on vm-gitlab subsection to infra/README.md so
the dockerised dev mode scales to a multi-dev team: one shared CA
held on vm-gitlab, public rootCA.pem distributed to each developer's
Windows trust store, R&D Lead mints per-VM certs on vm-gitlab. The
CA private key never leaves vm-gitlab.

The solo flow already in the HTTPS dev-server setup section stays
the entry point for the first dev; this subsection picks up where
that one ends and answers the next question — how a teammate can
browse another dev's VM with a green padlock.

Covers initial CA setup on vm-gitlab, the canonical mkcert per-VM
mint command, onboarding a new dev (rootCA.pem + per-VM cert
delivery + Windows-side import), and operational notes (departures,
CA rotation, per-VM rotation, migration to a future corp-CA cert).

No code changed.
julien merged commit 2ffbfc4034 into main 2026-06-01 23:30:56 +02:00
julien deleted branch docs/team-mkcert-ca 2026-06-01 23:30:59 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adastra-bot (AdAstra Bot) julien (Julien Gautier)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: julien/apf_portal#264
Delete Branch "docs/team-mkcert-ca"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?