Aller au contenu

Helios (Practice Websites)

Scope

This page covers Helios infrastructure managed from the Aether repo — nginx configs, environment files, monitoring rules, and the aether-side deployment pattern.

For Helios application specifics (content editing, adding a practice workflow, Next.js deploy via Helios's own Makefile), see the Helios repo's own docs:

  • helios/repo/docs/adding-a-practice.md — full practice onboarding walkthrough
  • helios/repo/docs/operations.md — content updates, image pipeline, cache invalidation

Architecture

Helios is a multi-tenant Next.js frontend serving 9+ dental practice websites from a single codebase. Each practice has its own domain and its own config in Aletheia.

                      ┌──────────────────────────────────────┐
                      │         nginx (aether)               │
                      │  cabinet-dentaire-aubagne.fr       ──┐
                      │  le-canet.chirurgiens-dentistes.fr ──┤
                      │  cabinet-bodin.fr                  ──┼── helios-prod-web:3000
                      │  dr-david-simon...                 ──┤
                      │  cda.groupe-suffren.com            ──┤
                      │  vsm.groupe-suffren.com            ──┤
                      │  ...                               ──┘
                      └──────────┬───────────────────────────┘
                                 │
                                 ▼
                     ┌──────────────────────────┐
                     │   helios-{env}-web       │
                     │   (Next.js + Node.js)    │
                     └────────────┬─────────────┘
                                  │ REST
                                  ▼
                     ┌──────────────────────────┐
                     │   aletheia-{env}-web     │
                     │   /api/v1/websites       │
                     └──────────────────────────┘

One Next.js container per environment serves all practice sites; routing by Host header is done in nginx and in the Next.js middleware.

Managed by Aether

Nginx vhosts

Three base configs (one per environment) in nginx/conf.d/:

  • helios-prod.conf.full + .conf.temp
  • helios-staging.conf.full + .conf.temp
  • helios-dev.conf.full + .conf.temp

Each prod vhost file handles multiple domains — practice domains + preview subdomains — routing them all to the same helios-prod-web:3000 upstream. Distinguishing by practice is done by Helios itself via the Host header.

Monitored domains

SSL certificate monitoring:

  • https://aletheia.groupe-suffren.com
  • https://aletheia-staging.groupe-suffren.com
  • https://aletheia-dev.groupe-suffren.com
  • https://monitoring.groupe-suffren.com
  • https://cabinet-dentaire-aubagne.fr
  • https://le-canet.chirurgiens-dentistes.fr
  • https://cabinet-bodin.fr
  • https://dr-david-simon.chirurgiens-dentistes.fr
  • https://cda.groupe-suffren.com
  • https://vsm.groupe-suffren.com
  • https://pds.groupe-suffren.com
  • https://ths.groupe-suffren.com
  • https://cda-staging.groupe-suffren.com
  • https://vsm-staging.groupe-suffren.com
  • https://cda-dev.groupe-suffren.com
  • https://vsm-dev.groupe-suffren.com

Aletheia backend health monitoring (HealthCheckFailing):

  • https://aletheia.groupe-suffren.com/health/
  • https://aletheia-staging.groupe-suffren.com/health/
  • https://aletheia-dev.groupe-suffren.com/health/
  • https://aletheia-staging.groupe-suffren.com/api/v1/websites/sites/cabinet-dentaire-aubagne.fr/config/

Helios frontend reachability (HeliosHealthCheckFailing — does not detect backend outages):

  • https://cabinet-dentaire-aubagne.fr
  • https://le-canet.chirurgiens-dentistes.fr

Helios-specific alerts

Alert Condition Source
HeliosContainerDown Web container missing > 2 min helios.rules.yml
HeliosContainerRestarting > 2 restarts in 15 min helios.rules.yml
HeliosHealthCheckFailing Practice site probe failing > 5 min helios.rules.yml
HeliosSSLExpiringSoon Practice domain cert < 14 days helios.rules.yml

See runbooks for the response procedures.

Environment files

Encrypted env files for Helios live in envs/helios/ in the aether repo (see environment management for the full list):

  • envs/helios/.env.dev.enc
  • envs/helios/.env.staging.enc
  • envs/helios/.env.prod.enc

Each contains:

Variable Purpose
ALETHEIA_API_URL Internal URL Helios uses to fetch content (e.g., http://aletheia-prod-web:8000/api/v1/websites)
REVALIDATION_SECRET Shared secret for Aletheia → Helios ISR webhook (Next.js cache invalidation)
NODE_ENV Always production (even for dev/staging — this is about Next.js optimization, not environment)
ENVIRONMENT prod, staging, or dev — used for logging/sentry tagging

Bootstrapping a new Helios install

For a brand-new deployment (fresh server or first Helios deploy on an existing server):

cd /opt/docker/aether/repo && make helios-init

This target:

  1. Creates /opt/docker/helios/{repo,envs}/ on the server
  2. Generates .env.{prod,staging,dev} with fresh REVALIDATION_SECRET values
  3. Deploys nginx configs for Helios domains
  4. Deploys monitoring rules (helios.rules.yml)
  5. Reloads nginx and Prometheus

After helios-init:

  1. Copy the printed REVALIDATION_SECRET values into the matching Aletheia env files (HELIOS_REVALIDATION_SECRET)
  2. Clone the Helios repo: git clone git@github.com:baudry-suffren/helios.git /opt/docker/helios/repo
  3. Obtain SSL certificates for practice domains (setup.sh only handles *.groupe-suffren.com)
  4. Deploy: cd /opt/docker/helios/repo && make deploy ENV=prod
  5. Run make encrypt in aether to persist the new secrets

Deploying Helios updates

Helios-side deploys (code, content, dependencies) happen from the Helios repo:

cd /opt/docker/helios/repo
make deploy ENV=prod        # deploys current branch
make deploy ENV=prod REF=v1.2  # deploys a tag

Aether-side deploys only needed when Helios infrastructure changes:

Change How to deploy
New practice domain added to nginx configs cd aether && make deploy && make restart-nginx
New alert rule in helios.rules.yml cd aether && make deploy (Prometheus auto-reloads)
Env variable change Edit server env file → make restart in helios repo → make encrypt in aether
New environment added (e.g. helios-qa) Create new .env.qa + new nginx config + redeploy

Adding a New Practice

This is primarily a Helios-side task. From aether, you only need to:

  1. Add the practice domain to nginx:
    • Edit nginx/conf.d/helios-prod.conf.full → add a new server_name line
    • Or add a new dedicated .conf.full if the domain needs special handling
  2. Obtain SSL cert: 
    docker exec certbot certbot certonly --webroot -w /var/www/certbot \
  --non-interactive --agree-tos --email admin@groupe-suffren.com \
  -d nouveau-cabinet.fr -d www.nouveau-cabinet.fr
  3. Add to monitoring: edit monitoring/prometheus/prometheus.yml (blackbox-ssl job) to include the new domain
  4. Deploy: make deploy && make restart-nginx

For everything else (SiteConfig in Aletheia, Helios deploy, DNS setup, content creation), see Helios's adding-a-practice guide.

Troubleshooting

Practice site returns 502: Helios container is down or network-isolated. Check docker ps --filter name=helios-prod and docker logs helios-prod-web.

Content changes don't appear on the site: ISR revalidation webhook failed. Check Aletheia's logs for REVALIDATION_SECRET mismatches, and verify Next.js is reachable from Aletheia: docker exec aletheia-prod-web curl http://helios-prod-web:3000/api/revalidate.

SSL cert expiring: see SSL Certificate Expiring runbook. Practice domains renew the same way as groupe-suffren.com domains.

New practice added but site 404s: verify the domain resolves, reaches nginx (curl -v https://newdomain.fr), that nginx has a matching server_name, and that Helios's Next.js router knows about the practice (Aletheia SiteConfig with matching domain).