Skip to content

Guide: Python services in fghj

Nothing in fghj is Python-aware, and this guide is mostly ordinary Docker advice with the fghj-shaped parts called out. There are four places where Python specifically trips people up here:

  • Binding to localhost, which means nothing outside the container.
  • Buffered stdout, which makes a working service look silent.
  • healthcheck with no curl, because the slim images don’t ship one.
  • Absolute URLs, because fghj’s proxy terminates TLS and sends plain HTTP to your port, and Uvicorn ignores X-Forwarded-* by default.

Everything else is the same .fghj.yaml any other runtime writes.

Dockerfile
FROM python:3.13-slim
# Dependencies in their own layer, before the source: editing a .py file
# then doesn't re-run pip.
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY app ./app
# Without this, print() and logging go into a pipe buffer and you see
# nothing in the UI's log pane until the process exits or writes 8 KiB.
# This single line is the most common fix for "my container produces no
# logs".
ENV PYTHONUNBUFFERED=1
# --host 0.0.0.0, always. Uvicorn's default is 127.0.0.1, which inside a
# container means the loopback of that container and nothing else: the
# published port connects and then gets nothing.
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
.fghj.yaml
version: "2.0"
services:
api:
build:
context: .
ports:
"8000":
primary: true
environment:
OWN_URL: https://${FGHJ_SERVICE_FQDN_HTTP}
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 2
retries: 15

That’s a service answering at https://api.<repo>.<workspace>.fghj.internal with real HTTPS. Note that ports is keyed by the number your app actually listens on — it’s the container port, not a label.

python:3.13-slim has no curl and no wget. Rather than installing one just to poll yourself, use the interpreter you already have:

healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]

urlopen raises on a non-2xx status, which exits non-zero, which is exactly what Docker reads as unhealthy. No sys.exit bookkeeping needed.

A node that declares a healthcheck is automatically waited on: anything that depends on it doesn’t start until Docker reports it healthy. There is no depends_on: {condition: ...} to write — declaring the check is the declaration.

The proxy terminates TLS on the host and relays plain HTTP to your container’s port, adding X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-For to every request. Uvicorn only reads them with --proxy-headers, and only from the addresses in --forwarded-allow-ips, which defaults to 127.0.0.1. The proxy’s connection arrives from Docker’s network, not the container’s own loopback, so allow it explicitly:

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", \
"--proxy-headers", "--forwarded-allow-ips", "*"]

request.url_for(...) then returns https:// URLs. Values a client already sent are kept, so a gateway in front of your service can pass along what the browser asked for.

As in Compose, Postgres is another service, with image: instead of build:, and your service depends_on it:

environment:
DATABASE_URL: postgresql://app:dev@${FGHJ_SERVICE_FQDN:db}:5432/app
depends_on:
db: {condition: service_healthy}
db:
image: postgres:16
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: dev
POSTGRES_DB: app
ports: ["5432"]
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 2
retries: 15
stop_grace_period: 30
volumes:
- name: pgdata
container: /var/lib/postgresql/data

${FGHJ_SERVICE_FQDN:db} expands to that container’s raw domain — direct to the container IP, no proxy, no TLS, on the real port. It’s the right address for a connection string and for every service-to-service call that isn’t specifically about the proxied HTTPS identity.

Use psycopg[binary] in requirements.txt rather than plain psycopg: the binary wheel carries its own libpq, so the image needs no libpq-dev/gcc and the build stays three lines.

A migration is a container that’s supposed to exit. migrates: names the database it writes to, and that’s what makes it a task:

api:
# ...
depends_on:
db: {condition: service_healthy}
migrate:
build: .
command: ["alembic", "upgrade", "head"]
migrates: db
environment:
DATABASE_URL: postgresql://app:dev@${FGHJ_SERVICE_FQDN:db}:5432/app

build: . is the same build as your service — your code and your alembic/ directory, with a different command. migrates: db puts it behind the database (after Postgres is healthy, since db has a healthcheck), and puts everything that waits on db behind it — api doesn’t have to say so.

A task isn’t considered started until it has finished, and a non-zero exit fails the node and blocks everything downstream. A migration that fails therefore stops the service coming up against an unmigrated database, instead of racing it.

It runs on every start of db, so the command must be idempotent — alembic upgrade head is. Fixtures go in a separate service with seeds: [db], which runs only when the database is new — see the reference.

Mount your source over what the image built and let uvicorn watch it:

command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
volumes:
- host: ./app
container: /app/app

Mount the source directory only, never /app itself: a bind mount at /app would also shadow anything the image put there, and if you ever install your project into the image (pip install -e .) it will shadow the egg-link too. Relative host paths resolve against this repo’s checkout root.

Add __pycache__ and .venv to .dockerignore while you’re there — a local virtualenv copied into the build context is both slow and, if its paths leak, wrong.

debug: publishes a port and nothing else; starting the debugger is the image’s job. The idiomatic hook in Python is sitecustomize.py, which every Python process imports at startup — so it survives gunicorn, forks, and shell wrappers without having to be PID 1:

RUN pip install --no-cache-dir debugpy
COPY sitecustomize.py /usr/local/lib/fghj/
ENV PYTHONPATH=/usr/local/lib/fghj
sitecustomize.py
import os
# One process has to own the port. Setting our own marker means forked or
# re-exec'd children inherit it and skip — the kind of variable worth
# having, and it's yours: fghj injects nothing here.
if not os.environ.get("APP_DEBUGPY_LISTENING"):
os.environ["APP_DEBUGPY_LISTENING"] = "1"
import debugpy
debugpy.listen(("0.0.0.0", 5678))
if os.environ.get("FGHJ_DEBUG_WAIT"):
debugpy.wait_for_client()
debug: 5678

Attach to api.<repo>.<workspace>.fghj.raw.internal:5678. Listening costs essentially nothing and can’t stop anything, which is why it isn’t gated — a breakpoint doesn’t exist until an IDE has attached and sent one. FGHJ_DEBUG_WAIT is the per-container switch in the UI for the one case attaching can’t reach: code that runs during startup.

Two caveats specific to this hook: python -S and python -E bypass it entirely (-S skips site, -E ignores PYTHONPATH), and PyCharm’s remote debugger speaks to its own pydevd-pycharm package rather than debugpy — same idea, different pip install.

Attaching a debugger has the whole contract, and tutorial chapter 7 walks through a breakpoint catching a request mid-flight (in Node, but the shape is the same).

SymptomCause
Port connects, nothing answersBound to 127.0.0.1. Use --host 0.0.0.0.
No logs at allMissing PYTHONUNBUFFERED=1 (or python -u).
Healthcheck always failsNo curl in the slim image — poll with python -c.
Redirects go to http://Uvicorn isn’t reading X-Forwarded-Proto. Add --proxy-headers --forwarded-allow-ips '*'.
pip install on every editCOPY requirements.txt before COPY app.
Debugger port already in useSeveral Python processes ran sitecustomize.py. Use the marker variable above.