2 · Environment domains + SSL

TL;DR

Objective — give each environment row in Zaj-PROJECT.md a reachable hostname and a valid certificate before the first deploy (Deployer flips a symlink, it doesn’t issue certs), so the deploy lands on a working HTTPS origin.

Steps at a glance:

1. Plan the environment hostname map — Decide the hostnames up front so DNS, certs, and your app’s APP_URL all agree.
2. Add the DNS records — Create one record per host at your DNS provider (or Cloudflare — see 6 · Cloudflare CDN).
3. Provision the SSL/TLS certificate — Use your host’s automated Let’s Encrypt integration (cPanel AutoSSL, Forge, Ploi, or certbot).
4. Verify with five CLI checks — Don’t trust the browser — run these and read the output.

User part + done-when

👤 User part — the user authorizes DNS records and certificate provisioning in the DNS provider / hosting panel. With an authorized browser/API path, an agent can drive the non-secret console flow, plan the hostnames, and run the five CLI verification checks. Without provider access, the user completes the panel actions and the agent verifies them.

Done when every hostname resolves via dig to the right IP, HTTPS returns 200/301, HTTP force-redirects to HTTPS, and the cert is valid, covers the host, and auto-renews.  ·  ⏱ ~20–40 min (+ DNS propagation)  ·  🔀 mixed (👤 DNS/cert dashboards, 🤖 verification).

Background

Every non-production and production row in Zaj-PROJECT.md needs a reachable hostname and a valid certificate before the first deploy — Deployer flips a symlink, it doesn’t issue certs. This page gets DNS and TLS green so the deploy lands on a working HTTPS origin. The common one-staging setup is only an example; projects can use qa, uat, client-demo, sandbox, or several non-production rows.

Steps

1. Plan the environment hostname map

Decide the hostnames up front so DNS, certs, and your app’s APP_URL all agree.

Environment key	Example host	Points to
staging-primary	nonprod.example.com	Selected non-production server IP (or Cloudflare proxy)
qa / uat / client-demo	qa.example.com / uat.example.com / demo.example.com	The server IP recorded for that environment row
Production	app.example.com / example.com	Production server IP
Apex redirect	example.com → www (or vice-versa)	Pick one canonical, 301 the other

Keep apex vs www decisions consistent with APP_URL in 3 · Production .env. A mismatch breaks absolute URLs, signed routes, and cookie domains.

Record the final URL/domain, host/IP, and noindex/robots posture in Zaj-PROJECT.md before you create records. If there is no non-production URL yet, leave that row pending and do not enter Phase 5 until a real target is selected.

2. Add the DNS records

Create one record per host at your DNS provider (or Cloudflare — see 6 · Cloudflare CDN).

Who does this

👤 User / authorized agent adds each DNS record in the DNS provider’s dashboard because this mutates live DNS. The agent prepares the exact rows, records the intended state, and verifies with dig.

Type	Name	Value	Notes
A	<non-production-host>	<server IPv4>	Use the host from the selected Zaj-PROJECT.md row
AAAA	<non-production-host>	<server IPv6>	Only if the server has IPv6
CNAME	www	example.com	Alias one name to the canonical

Propagation is not instant

DNS changes can take minutes to hours. Verify with dig (below) rather than a browser, which caches aggressively. Lower the TTL before a planned cutover.

Production over Cloudflare — avoid a public 525

For the production hostname, Cloudflare proxying is only safe after DNS points at the current origin and the origin serves a valid certificate. A Cloudflare 525 SSL handshake failed is expected while origin TLS is missing, but it is not an acceptable parked state for a public domain.

Bring-up order:

1. Point the production A record at the current origin IP from Zaj-PROJECT.md.
2. If Hostinger/Let’s Encrypt needs direct validation, keep the record DNS-only (grey cloud) during certificate issuance.
3. Issue the origin cert in the hosting panel.
4. Re-proxy (orange cloud), then set Cloudflare SSL to Full (Strict).
5. Deploy the app only after DNS + origin TLS are coherent.

Stale-DNS check first:

PROD_DOMAIN="<production-domain-from-Zaj-PROJECT>"
EXPECTED_ORIGIN_IP="<production-origin-ip-from-Zaj-PROJECT>"
dig +short "$PROD_DOMAIN" A | grep -Fx "$EXPECTED_ORIGIN_IP"
# Expected: the production domain resolves to the current origin box before SSL/proxy work continues

Safe mutation rule: grey-clouding a pre-launch hostname is fine. Grey-clouding a live hostname is a real traffic change — stop for an explicit maintenance window / user approval, record the previous proxy state, and be ready to revert.

3. Provision the SSL/TLS certificate

Use your host’s automated Let’s Encrypt integration (cPanel AutoSSL, Forge, Ploi, or certbot). One cert per hostname, or a wildcard if your panel supports DNS-01.

Who does this

👤 User / authorized agent issues the certificate in the hosting panel (AutoSSL / Forge / Ploi) because it changes provider state. The agent verifies the result with curl/TLS checks after issuance.

• Issue for every hostname that serves traffic, including www.
• Enable auto-renewal — Let’s Encrypt certs expire every 90 days.
• Force HTTP → HTTPS at the web server (or via Cloudflare “Always Use HTTPS”).

Hostinger AutoSSL stuck on Installing

If Hostinger AutoSSL / Let’s Encrypt sits on Installing for more than ~15–20 minutes while Cloudflare is orange-clouded, validation likely cannot reach the origin. Cancel/retry after switching the relevant record to DNS-only for issuance, then re-proxy and set Cloudflare SSL to Full (Strict) after the origin cert is active.

4. Verify with five CLI checks

Don’t trust the browser — run these and read the output.

1. Run the five-check verification pass.

   HOST="nonprod.example.com" # replace with the selected URL/domain from Zaj-PROJECT.md
   
   # 1) DNS resolves to the expected IP
   dig +short "$HOST"
   
   # 2) HTTPS responds (expect HTTP/2 200 or 301/302 to the canonical host)
   curl -sI "https://$HOST" | head -1
   
   # 3) HTTP redirects to HTTPS (expect 301/308 with a https:// Location)
   curl -sI "http://$HOST" | grep -iE 'HTTP/|location'
   
   # 4) Behind Cloudflare? Confirm the proxy is in front
   curl -sI "https://$HOST" | grep -i 'cf-ray' && echo "proxied" || echo "direct"
   
   # 5) Certificate is valid and covers the host
   echo | openssl s_client -connect "$HOST:443" -servername "$HOST" 2>/dev/null \
     | openssl x509 -noout -subject -issuer -dates
   # Expected: dig returns your IP, HEAD is 200/301, HTTP redirects to HTTPS, and the cert notAfter is in the future with subject matching the host

   • ✅ dig returns your IP, the HEAD request is 200/301, HTTP redirects to HTTPS, and the cert’s notAfter date is in the future and subject matches the host.

Troubleshooting

Symptom	Cause	Fix
dig returns nothing / wrong IP	Record missing or not propagated	Re-check the record; wait for TTL
curl cert error	Cert not issued / wrong host	Re-run AutoSSL; ensure host is in the cert SAN
Hostinger SSL stays Installing	Let’s Encrypt validation cannot reach the current origin, often because Cloudflare is still proxied	Temporarily DNS-only the record for issuance, cancel/retry SSL, then re-proxy after the cert is active
Cloudflare 525 on production	Cloudflare reached an origin with no valid TLS, or DNS still points to a stale/wrong origin	First run the stale-DNS check against the current origin IP; then grey-cloud if needed, issue the origin cert, re-proxy, and use Full (Strict)
Redirect loop	Cloudflare SSL mode Flexible + origin forcing HTTPS	Set Cloudflare SSL to Full (Strict) (see page 6)
NET::ERR_CERT_COMMON_NAME_INVALID	Cert doesn’t list this host	Reissue covering all hostnames

Cloudflare proof vs raw origin proof

After re-proxying, Cloudflare Full (Strict) + HTTPS 200 is the production proof. A raw openssl s_client to a shared-origin IP can show a different default certificate unless SNI and the intended hostname are used, so treat it as a diagnostic, not the final pass/fail signal.

Checklist

Do not mark this step done until every box below is checked.

• 🤖 Hostnames resolve — every environment hostname resolves via dig to the correct IP.
• 🤖 HTTPS + redirect — HTTPS returns 200/301 and HTTP force-redirects to HTTPS.
• 🔀 Production Cloudflare safe — production is not orange-clouded until the stale-DNS check matches the current origin and origin TLS is valid; any live grey-cloud window had explicit approval and rollback notes.
• 👤 Cert valid + auto-renew — certificate is valid, covers the host, and auto-renewal is on.
• 🔀 Project state updated — Zaj-PROJECT.md records each environment URL/domain, DNS target, and noindex/robots posture.
• 🔀 Canonical matches APP_URL — apex vs www decision matches the planned APP_URL.

→Next step

Production .env