DEV Community

Cover image for TDK CLI Roadmap
localeostackio
localeostackio

Posted on

TDK CLI Roadmap

#cli #learning #opensource #tutorial

A step-by-step path from your first tdk up to running a full multi-service stack on your machine. Work through the stages in order. Each stage builds on the one before it, and you can check off topics as you go.

Learning path for TDK CLI. Practice projects are in the TDK example repositories.

flowchart TD
    A[Start: Prerequisites] --> B[Stage 1: First Stack]
    B --> C[Stage 2: service.json]
    C --> D[Stage 3: Generated Files]
    D --> E[Stage 4: Running and Inspecting]
    E --> F[Stage 5: Multi-Service Stacks]
    F --> G[Stage 6: Data and Messaging]
    G --> H[Stage 7: Routing and Gateway]
    H --> I[Stage 8: Team Workflow]
    I --> J[Stage 9: Production Handoff]

Stage 0: Prerequisites

  • [ ] Docker installed and running
  • [ ] Basic terminal skills: directories, running commands, reading logs
  • [ ] Understanding of what a container is (an isolated, runnable package of a process)
  • [ ] Node, Bun, Python, or Go installed, depending on the service you want to run

Stage 1: Your First Stack

  • [ ] Install TDK CLI
  • [ ] Create a project folder and move into it
  • [ ] Add one simple service
  • [ ] Run tdk up and wait for the stack to start
  • [ ] Open the service in a browser or with curl
  • [ ] Stop the stack and start it again

Goal: You can start one service with a single command.

Stage 2: Describing a Service

  • [ ] Find the service.json file for your service
  • [ ] Learn what the runtime field declares
  • [ ] Learn how a port is declared and exposed
  • [ ] Change a value in service.json, then run tdk up again
  • [ ] Understand that service.json is the source of truth, not the generated files

Goal: You know that you describe services, and TDK derives the rest.

Stage 3: Generated Files

  • [ ] Find the generated Dockerfile for your service
  • [ ] Find the generated Traefik routing configuration
  • [ ] Find the generated Tiltfile
  • [ ] Read the generated files and match them to your service.json
  • [ ] Read what TDK writes
  • [ ] Learn what drift means and how TDK reports it
  • [ ] Fix drift by updating the source, not the generated file

Goal: You trust generated files because you can explain each one.

Stage 4: Running and Inspecting

  • [ ] Open the dashboard with tdk ui
  • [ ] Move around with ↑/↓ or j/k
  • [ ] Search with /
  • [ ] Switch tabs with 1 to 5
  • [ ] Read the logs for a service
  • [ ] Find which service is failing and why
  • [ ] Check the Tilt view for live updates

Goal: You can tell which service is healthy and which is failing, without guessing.

Stage 5: Multi-Service Stacks

  • [ ] Add a second service in its own folder with its own service.json
  • [ ] Make the two services call each other by name
  • [ ] Add a third service and draw the call graph
  • [ ] Start the whole stack with one tdk up
  • [ ] Edit code in one service and watch the others keep running
  • [ ] Practice with the ERP example or the e-commerce example

Goal: You can run and change a system of several services together.

Stage 6: Data and Messaging

  • [ ] Add a relational database as a service in the stack
  • [ ] Run migrations against it, using a tool such as Prisma, Drizzle, Atlas, or Dbmate
  • [ ] Make a service wait until the database is ready
  • [ ] Add a messaging service such as NATS
  • [ ] Publish and consume one event between two services
  • [ ] Check that a service survives a restart of the database

Goal: Your stack includes state and events, not only HTTP calls.

Stage 7: Routing and Gateway

  • [ ] Learn how Traefik routes traffic to services
  • [ ] Give each service a stable path or hostname
  • [ ] Call every service through the gateway, not a raw port
  • [ ] Check routing rules in the generated configuration
  • [ ] Remove a hardcoded port from a client and use the gateway instead

Goal: Clients use the same addresses locally that they will use in production.

Stage 8: Team Workflow

  • [ ] Commit service.json files to version control
  • [ ] Run drift checks in CI, so generated config never goes stale
  • [ ] Write a README that gives one command to start the stack
  • [ ] Onboard a teammate on a clean machine using only that README
  • [ ] Agree on naming, ports, and routing conventions across services

Goal: A new developer can start the whole stack without help.

Stage 9: Production Handoff

  • [ ] Remember that TDK CLI is for local development, not deployment
  • [ ] Choose a deployment path: Helm, Argo CD, or Kustomize
  • [ ] Keep production configuration in the deployment repository
  • [ ] Verify that service names and routes match between local and production
  • [ ] Keep staging or load testing on environments built for them

Goal: Local work leads cleanly to a deployed system.

Where to go next

Top comments (0)