Guide: choosing HTTP, HTTPS, or raw for a service call
This page is the “how do I actually configure this” companion to a handful of concept pages that each cover one piece of the underlying design: Node identity & domains, Split DNS, In-network TLS proxy sidecar, and Local CA & TLS proxy. Read those for the why; this page is the how, with worked examples pulled from real bugs found while wiring up a real multi-repo workspace.
The one-paragraph mental model
Section titled “The one-paragraph mental model”Every node gets two domains, always differing only in suffix:
{node}.{workspace}.fghj.raw.internal— raw/direct. From inside the run’s own docker network it resolves straight to the real container IP, on any port the container listens on. From the host the same name also works: fghjd hands out a per-node virtual IP, listens on it, and forwards to the port Docker published, sodb.myworkspace.fghj.raw.internal:5432is the port the author declared, not the one Docker picked (see Node identity & domains). The host side reaches only declared ports. Either way: no TLS, no certificate, fastest path, no CA trust needed.{node}.{workspace}.fghj.internal— HTTP(S)-canonical, proxied. Resolves to the run’s sidecar from inside the network, and to the host proxy from the host/a browser outside it — the same hostname either way. Only ever reachable on 80 (plain HTTP, routed byHost) or 443 (terminates TLS with a real, locally-CA-signed cert, routed by SNI). Both are proxied and both are recorded; a request is answered in the scheme it came in. Never any other port.
Nearly every bug in this area comes from picking the wrong one of these two for a given call, or from combining the http domain with a raw port number (which can never work — see the pitfall below).
Decision guide
Section titled “Decision guide”Ask this about the specific call you’re configuring:
Does anything outside this run’s docker network (the host, a browser, a
real pip/npm/twine/curl process on your machine, a webhook sender,
an OAuth provider) ever need to dial this exact URL?
- No — it’s purely container-to-container (a database connection string, an internal API call, a cache, a message broker): use the raw zone. This is the default and covers nearly every case.
- Yes (a presigned S3 URL you hand back to an uploader/downloader, an OAuth redirect URI, a webhook callback URL, anything a browser will navigate to): use the http zone, and make sure the container minting that URL also trusts fghj’s CA if it dials that same URL itself (not just hands it out).
Do you want to see the call in the callee’s Traffic tab? Only the http
zone is proxied, so only a call to a *.fghj.internal name is ever
recorded. A raw call goes straight from one container to the other with
nothing in between to watch it. For an HTTP API you’ll be debugging, a
frontend’s /api/ proxy for instance, the http zone is worth the extra
hop. It doesn’t have to cost TLS: http:// to an http-zone name is proxied
and recorded just like https://. If the caller is nginx and you do use
https://, it needs one extra
line.
The macros
Section titled “The macros”In .fghj.yaml, environment/env_file values can reference a domain
without hand-computing it. The Macros reference has
the full rules; here’s which one to pick:
| Token | Zone | Use for |
|---|---|---|
${FGHJ_SERVICE_FQDN} | raw (this node’s own) | Rare — a node referencing its own raw address. |
${FGHJ_SERVICE_FQDN:name} | raw (service name in this repo) | The default choice. DATABASE_URL, a cache, a broker, anything container-to-container you won’t need to watch. |
${FGHJ_SERVICE_FQDN:alias/name} | raw (service name in the repo included as alias) | The same, across repos. |
${FGHJ_SERVICE_FQDN_HTTP} | http (this node’s own) | This node minting a URL that points back at itself (e.g. an absolute callback URL for its own OAuth flow). |
${FGHJ_SERVICE_FQDN_HTTP:name} / :alias/name | http (another service’s) | A sibling’s proxied identity — the minio/presigned-URL case below, or an HTTP call you want recorded. |
A name that matches no service is a blocking warning, not a literal left in
the container’s environment. They can’t reach a named port on another
service — only its bare domain — so referencing a sibling’s
named port (e.g. a management port declared via #Port.name) has to
be a hand-typed literal string. That’s exactly where the pitfall below
tends to get introduced.
Worked example 1: an ordinary internal call (do this by default)
Section titled “Worked example 1: an ordinary internal call (do this by default)”A php service talking to its own mysql — purely
internal, no external consumer ever sees this hostname:
environment: MYSQL_HOST: ${FGHJ_SERVICE_FQDN:mysql}Nothing else needed. No CA trust, no port suffix (raw ports are supplied
separately, e.g. :3306, or the app’s own default), works identically
whether mysql shares the container network with a Docker-native lookup —
because that’s exactly what this is.
Worked example 2: a sibling’s named port (can’t use the macro)
Section titled “Worked example 2: a sibling’s named port (can’t use the macro)”aikifactory declares a second port on itself, named management:
# aikifactory's own .fghj.yamlports: "8080": primary: true "8081": name: managementA consumer needing that specific port has to hand-type the domain, because the macro only reaches a sibling’s bare domain:
# the consuming service's .fghj.yamlenvironment: AIKIFACTORY_MANAGEMENT_URL: http://management.aikifactory.aikifactory.aikido.fghj.raw.internal:8081This is a purely internal call (nothing outside the network needs this
management API), so — per the decision guide above — it’s the raw
zone, scheme http://, and the real container port (8081) all
consistently paired together.
The #1 pitfall: fghj.internal + raw port number
Section titled “The #1 pitfall: fghj.internal + raw port number”The single most common mistake (found three times in one real workspace) is writing the http-zone domain with a raw port number:
# WRONG — this can never workAIKIFACTORY_MANAGEMENT_URL: http://management.aikifactory.aikifactory.aikido.fghj.internal:8081The fghj.internal suffix always resolves to the sidecar (or host proxy),
and the sidecar/host proxy only ever listens on 80, 443, and 53 — never
8081, never any other raw port. This fails with ECONNREFUSED <sidecar-ip>:8081 every single time, deterministically, regardless of
whether routes are fresh or containers were just restarted. It is easy to
misdiagnose as “stale DNS” or “the route table didn’t update,” because the
IP the domain resolves to looks like it should be wrong — but it’s actually
always correct; the port is just something that domain’s listener can
never serve. The fix is always the same: switch the domain’s suffix from
fghj.internal to fghj.raw.internal, keep the scheme and port exactly as
they were.
Worked example 3: a URL handed to an external caller (needs the http zone + CA trust)
Section titled “Worked example 3: a URL handed to an external caller (needs the http zone + CA trust)”aikifactory mints presigned S3 URLs against its minio backing
dependency, then hands them back to whoever is uploading/downloading a
package — which might be a real pip/twine/npm/mvn process running
on the host, well outside the run’s docker network:
environment: AIKIFACTORY_S3_ENDPOINT: https://${FGHJ_SERVICE_FQDN_HTTP:minio}Why not raw, and why not plain http, here specifically:
- Raw can’t be
https://at all. The raw zone goes straight to the container — there is no proxy in front of it, so nothing terminates TLS and no certificate is ever issued for afghj.raw.internalname. An S3 client, a browser, or anything else that expects ahttps://endpoint has no raw option. (Plainhttp://against the raw zone would reach a host-side caller, via the virtual-IP forwarder above — it just can’t be the TLS endpoint this case needs, and it leans on host plumbing the http zone doesn’t need.) - Plain
http://on the http zone stays plain HTTP. Port 80 relays it byHost, with no redirect (see Local CA & TLS proxy). That works for the container’s own calls, but a presigned URL is checked by an S3 client or a browser that expects anhttps://endpoint, and a browser page served over plain HTTP isn’t a secure context. - So
https://on the http zone is the combination this case needs — same hostname, same TLS cert, whether the request comes from inside the network (via the sidecar) or from the host (via the host-side proxy).
The one thing this needs that the raw zone never did: the container
minting and using this URL (here, aikifactory itself — it doesn’t just
hand the URL out, it also uses the same endpoint for its own internal S3
API calls) has to trust fghj’s local CA, or its own outbound HTTPS calls to
that domain will fail certificate verification.
Trusting fghj’s CA inside a container
Section titled “Trusting fghj’s CA inside a container”The files you need are already in the container. fghjd bind-mounts one
directory, read-only, into every container it starts:
| Path in every container | Contents |
|---|---|
/etc/fghj/certs/cert.pem | just fghj’s CA cert, PEM-encoded, no key material |
/etc/fghj/certs/bundle.pem | that same cert merged with this host’s own real root CA store — a complete trust store, not a single cert. On macOS that’s the Admin and System trust domains, so a CA trusted only in your login keychain isn’t included; on Linux, the system store. |
There is nothing to mount, no path on the host to name, and no .fghj.yaml
schema for it. What is left is activating them, which is one line of
environment:.
Pick the file by whether you’re adding or replacing
Section titled “Pick the file by whether you’re adding or replacing”This is the whole decision, and getting it backwards is the one way to break a working service:
- Replacing a trust store —
SSL_CERT_FILE,REQUESTS_CA_BUNDLE, overwriting/etc/ssl/certs/ca-certificates.crt— means the container now trusts only what you pointed it at. Usebundle.pem. Point one of these atcert.pemand the container trusts fghj and nothing else: every genuine external HTTPS call it makes (a real S3, a real OAuth provider) starts failing certificate verification. - Adding to a trust store. Only Node has a variable for this
(
NODE_EXTRA_CA_CERTS), and a shell can do it by appending. Usecert.pem— appending a copy of the host’s roots to a store that already has them achieves nothing.
One environment variable, no shell required
Section titled “One environment variable, no shell required”The common case, and the only one that also works for a scratch or
distroless image — a statically compiled Go binary, say — because nothing
has to run inside the container:
environment: SSL_CERT_FILE: /etc/fghj/certs/bundle.pemGo, OpenSSL (so curl, and anything linked against it), and Python’s ssl
module all honor SSL_CERT_FILE. Python’s requests reads
REQUESTS_CA_BUNDLE instead; set both if you’re not sure which path a
library takes.
Node is the exception worth knowing, because it’s additive — and so it wants the other file:
environment: NODE_EXTRA_CA_CERTS: /etc/fghj/certs/cert.pemAppending into the image’s own store
Section titled “Appending into the image’s own store”Some things read neither variable and only ever look at the canonical system path — Java, and a few statically-linked tools. If the image has a shell and a writable root filesystem, append fghj’s cert to the store the image already has, at startup, before your real process:
command: ["sh", "-c", "cat /etc/fghj/certs/cert.pem >> /etc/ssl/certs/ca-certificates.crt && exec my-server"]>>, not >: appending keeps the real CAs. This needs to run as root, and
it’s cert.pem rather than bundle.pem precisely because it’s additive.
Java honors none of the above — it reads its own keystore, so it needs an import rather than a file path:
command: ["sh", "-c", "keytool -importcert -noprompt -cacerts -storepass changeit -alias fghj -file /etc/fghj/certs/cert.pem && exec java -jar /app.jar"]Two things the mount can’t do for you
Section titled “Two things the mount can’t do for you”- It isn’t there during a build. The mount exists for containers, not for
BuildKit, so a
RUN apt-getorRUN npm installthat needs to dial the http zone can’t read/etc/fghj/certs. Usebuild.secretsto get the cert into a build step, or — usually simpler — have the build talk to the raw zone over plainhttp://, where no CA is involved at all. - It can’t help an image with no filesystem at all to write to and no
environment support. That’s a short list, and
SSL_CERT_FILEcovers effectively all of it.
Why fghj doesn’t just turn it on
Section titled “Why fghj doesn’t just turn it on”Mounting is free; activating isn’t. As the table above says, nearly every
mechanism Unix offers for trusting an extra CA replaces the container’s
trust store rather than extending it. Setting SSL_CERT_FILE on every
container by default would silently swap each one’s idea of the public
internet for fghj’s — a change an image’s author never asked for, invisible
until some unrelated outbound call fails. So the files are simply there, at a
stable path, costing nothing, for the configs that ask.
The files themselves stay correct on their own: fghjd rewrites both on every
start (see ca::refresh_trust_files), so if fghj’s local CA is ever
regenerated — normally a one-time, per-machine event that should never happen
in ordinary use — the mounted copies follow, with nothing to remember to
rebuild. The host-side originals live in /var/lib/fghjd/certs/, separate
from /var/lib/fghjd/ca/ so that no private key is ever inside the
directory every container can read.
Quick reference
Section titled “Quick reference”| Scenario | Zone | Scheme/port | CA trust needed in the caller? |
|---|---|---|---|
| DB/cache/broker connection string | raw | whatever the backing service speaks | No |
| Internal API call, own or named port | raw | http://...:<port> | No |
| This node’s own primary port, called internally | raw | http://<raw-domain> (primary port implied) | No |
| Internal HTTP call you want recorded | http | http://<http-domain> or https://<http-domain> (no port) | Only over https:// |
| Presigned URL / OAuth redirect / webhook URL handed to an external caller | http | https://<http-domain> (no port — only 80/443 exist) | Yes, if this same container also dials that URL itself |
fghj.internal + a raw port number | — | never valid | — |