Document running the template inside a TDK landscape (and the port conflict to avoid)

[kburym]

Summary

Request for a small, optional way to use the template's docker compose setup together with TDK CLI in a local multi-service setup, or, if that is not wanted here, for guidance on where such a note should live.

What TDK is

TDK (Tilt Development Kit, @tdk-landscape/tdk-cli-core) is a local multi-service runner. Every service has a service.json, and tdk up <stack> starts that slice with Docker + Tilt, health-checked boot order and *.localhost routing through Traefik. It is not a deploy tool and not a production Compose replacement. Requirements: Docker, Tilt, Bun (for the services it generates).

Tool	Owns
the template's docker compose setup	A FastAPI + React + Postgres project template with its own Compose files
tdk project / tdk resource / tdk up	The local landscape: ports, stacks, Docker, Tilt, proxy

Why this might fit

TDK also scaffolds a FastAPI service (tdk resource api --type backend --language python), so there is real overlap in users. There is one concrete interaction worth documenting: TDK's local proxy needs ports 80, 443 and 5432 free, and the template's Compose setup also wants a proxy and a database.

What I am asking for

• A short note in the deployment or development docs saying how to run the template next to other services, and which ports collide with a TDK landscape. I will write it if you point me at the right file.
• No change to the template itself is requested.

Example flow:

# you provide the Dockerfile; TDK does not generate one for bring-your-own
# run only the template's backend inside a TDK stack
tdk resource shop-api --type bring-your-own --stack shop --dockerfile ./backend/Dockerfile
tdk up shop

Acceptance

• The note names the port conflicts and the recommended workaround.
• The template's default workflow is unchanged.
• Optional and additive. TDK is not a required toolchain and does not deploy anything.

Non-goals

• Replacing your deployment guidance. TDK is local-only.
• Making TDK a dependency of full-stack FastAPI.

Related

Companion issue on the TDK side (the provider or recipe that this depends on): tdk-landscape/tdk-cli-core#252

Disclosure: I'm one of the TDK maintainers, and I drafted this issue with AI assistance. TDK is a young, small project (1.3.x), so I'm keeping the ask small and optional. If this isn't a fit, or isn't wanted in the issue tracker, please just say so and I'll close it.