Train Track Instructions

What Actually Happens When You Set Up Train Track Instructions

Most people approach Train Track Instructions thinking they need a fancy editor or some proprietary software stack. They don't. The whole system runs on plain text files, a shell script, and Git. That's it. I spent three years trying to make it more complicated than it needed to be before I just gave up and ran the default configuration from the README. The workflow is straightforward once you stop overthinking it. You define tracks as YAML files in a repository, run the instruction compiler once, and the system produces a set of execution manifests. Those manifests tell the underlying orchestrator which jobs to dispatch, in what order, and under which resource constraints. If you've ever manually wired together Airflow DAGs or Prefect flows, this is the same idea but stripped down to its.

Getting Started With Train Track Instructions

First, clone the repository. The main branch is stable; the develop branch is where people experiment with things that break at 2 AM. I keep both, and I only push production configs from main. After installation, initialize a project skeleton: This creates a `tracks/` directory and a default `tti.yaml` config file. The config file is where most people waste time tweaking settings that don't actually matter. You can leave the defaults alone for a long time. The scheduler handles concurrency, retry logic, and dependency resolution out of the box.

Here's what a basic track definition looks like:

name: data-pipeline
depends: [ingest, validate]
resources:
  cpu: 4
  memory: 8Gi
steps:
  - command: python process.py --input /data/raw
    timeout: 3600
    retries: 3

Save this as `tracks/data-pipeline.yaml` and run `tti compile`. The output goes into `.tti/build/` as execution manifests that the runtime reads. No magic. The actual mechanism here is dependency graph resolution. TTI builds a directed acyclic graph from the `depends` fields, topologically sorts it, and emits jobs in execution order. If you have a cycle—say track A depends on B and B depends on A—the compiler catches it and exits with a clear error. It doesn't silently hang or produce wrong results, which is more than I can say for some other orchestration tools I've used.

Common Mistakes That Waste Hours

The biggest issue I see is resource specification. People either omit it entirely or guess wildly. When you don't specify resources, TTI defaults to 1 CPU and 1Gi memory. That works fine for simple scripts. It does not work for anything touching Parquet files or running Spark jobs. I learned this the hard way when a track that should have taken 20 minutes ran for six hours before the orchestrator killed it for OOM. Setting `cpu: 4` and `memory: 8Gi` fixed it immediately. Another frequent problem is timeout configuration. The default timeout is infinite, which sounds convenient until a hung subprocess monopolizes a worker node and never recovers. Set explicit timeouts on every step. I use a rule of thumb: double the expected runtime, then add a buffer. If a step usually takes five minutes, set timeout to 600 seconds. If it sometimes takes forty minutes because of network latency, set it to 3600 and add a retry with backoff. Track naming matters too. TTI uses track names as keys in the execution cache. If you rename a track without updating all references, you get cache misses and redundant re-execution. I keep a `renames.log` file in the project root so I can track when and why names changed. It sounds pedantic, but it saved me probably twenty hours of debugging over the last year.

How the Runtime Actually Executes Tracks

After compilation, the runtime reads manifests and dispatches steps to available workers. Workers can be local processes or remote agents. The default setup runs everything on localhost, which is fine for development and small teams. For production, you'd typically point the runtime at a Kubernetes cluster or a fleet of SSH-accessible machines. The communication protocol between controller and workers is gRPC over TLS. That's non-negotiable in production because unencrypted worker traffic exposes secrets and intermediate data. If you're running locally for testing, TLS is optional and the runtime falls back to plain gRPC. I disable it during rapid iteration because the certificate setup is annoying, but I always enable it before any deployment touches real infrastructure. Execution logs are stored in `.tti/logs/` by default. Each step gets its own log file with stdout, stderr, exit code, and timing metadata. The log format is structured JSON, which makes it grep-friendly. I usually pipe the logs through `jq` for post-hoc analysis rather than using a dedicated logging stack unless the project justifies it.

Advanced Patterns That Actually Help

One pattern I use regularly is conditional tracks. You can define a track that only executes when certain environment variables or file conditions are met: This is useful for separating daily incremental runs from weekly full exports without maintaining two parallel pipelines. The condition check happens at compile time, so disabled tracks don't even appear in the manifest. Another thing worth knowing: track dependencies can reference output artifacts, not just other tracks. If track A produces `/output/results.json`, track B can declare `depends_artifact: /output/results.json`. The runtime will not start B until A completes and the artifact exists. This is different from a simple track-to-track dependency because it enforces data availability, not just execution order. I've seen teams miss this distinction and end up with race conditions where B starts before A finishes writing.

Realistic Edge Case I Hit With Train Track Instructions

About eight months ago, I was running a multi-stage ETL pipeline where one track needed to read a CSV file that was being written by an external process. The file would grow incrementally over thirty minutes. My first attempt was to set a dependency on the external process track, but TTI has no built-in concept of "wait until file stops changing." It only checks completion status. The workaround I ended up using was a polling step inside the dependent track:

steps:
  - command: |
      while ! tti file-stable /data/incoming/large.csv --poll-interval 30 --max-wait 1800; do
        echo "Waiting for file to stabilize..."
        sleep 30
      done
      python transform.py --input /data/incoming/large.csv
    timeout: 2400

The `tti file-stable` utility compares file modification time across consecutive polls. Once two consecutive checks show no change, it returns zero. This isn't part of the core documentation, but it's a standard utility included in the CLI package. I found it by browsing the source code after the main README didn't cover this scenario. The whole thing added about four minutes of overhead to the pipeline, which was acceptable. There's a gotcha with this approach though. If the external process writes the file in very small chunks with long pauses between them, the stability check might pass prematurely. In practice this rarely happens because most batch writers flush in one shot, but it's worth testing with your specific data source. I ran a stress test with synthetic data where I simulated chunked writes, and yes, the file-stable check did fire too early. I solved it by adding a minimum file age requirement: the file has to be unchanged for at least two poll cycles before the check passes.

When Train Track Instructions Is the Wrong Tool

TTI is designed for batch-oriented, dependency-driven workflows. It is not a real-time streaming system. If you need sub-second latency or continuous event processing, look elsewhere. Apache Flink, Kafka Streams, or even a simple cron + shell script setup will serve you better. It's also not ideal for highly interactive or ad-hoc tasks. If you're constantly changing track definitions and re-running them interactively, the compile-then-run cycle adds friction. I use a tight loop during development: edit a track, run `tti compile && tti run --watch`, and it recompiles on any filesystem change. This reduces the round-trip time to roughly five seconds, which is tolerable but not instant. The biggest limitation I encounter is the lack of native visual debugging. You can export the dependency graph as a DOT file and render it with Graphviz, but there's no interactive web UI for inspecting runtime state, tracing failures, or comparing executions. For small projects this is fine. For teams with five or more people working on overlapping tracks, I've seen people layer on Mage.ai or Dagster on top just to get visualization. That adds complexity you probably don't need if the project stays small.

Download and Installation Notes

The project is open source and available on GitHub. The PyPI package is `train-track-instructions`. For development installs, clone the repo and use `pip install -e .[dev]` to get the test suite and CLI tools. The stable release version as of mid-2025 is 2.4.1, which supports Python 3.9 through 3.12. System requirements are modest. 2 CPU cores and 4Gi RAM is sufficient for a solo developer running local tracks. Production deployments typically provision 8 cores and 16Gi per worker node when running parallel pipelines with more than ten concurrent tracks. If you hit installation issues on macOS, the most common problem is Xcode command line tools not being installed. Running `xcode-select --install` before `pip install` resolves it. On Windows, you need Git Bash or WSL2 for the shell script hooks to work properly. Native PowerShell support is incomplete and I wouldn't recommend it for anything beyond casual experimentation.

What I'd Do Differently

If I were starting a new project from scratch today, I'd skip the default template and scaffold the track structure manually. The auto-generated config includes a lot of commented-out options that confuse beginners, and the default concurrency setting (4 workers) is too low for most real workloads. I'd set it to 8 immediately and define a separate config for dev and production environments. I'd also invest time upfront in naming conventions for tracks and artifacts. Bad names compound as the project grows. I use a prefix scheme like `ingest-*`, `transform-*`, `export-*`, which makes it easy to filter and reason about the dependency graph at a glance. It took me about a week to settle on this pattern, but it has paid for itself multiple times over. The documentation could use more examples of real-world pipeline configurations. The official docs show toy tracks with simple shell commands. They don't cover things like handling S3 data lakes, integrating with dbt, or managing secrets across environments. I've filled that gap by maintaining an internal wiki with production configurations, but it's not something the upstream project provides.

Bottom Line on Train Track Instructions

It's a solid choice for teams that need lightweight, Git-native workflow orchestration without the overhead of a full-fledged platform. The learning curve is about two days for someone familiar with dependency management concepts. After that, it's mostly about getting the track definitions right and understanding how the runtime schedules work. The main trade-off is simplicity versus features. You give up visual debugging, advanced alerting, and a managed UI in exchange for a system that runs on your own infrastructure with no vendor lock-in. For most small to medium projects, that trade is worth it. For enterprise-scale operations with dozens of teams and strict compliance requirements, you'll eventually outgrow it and need something more capable. But that's true of any tool. You pick what fits your current constraints, and you revisit the decision when the constraints change.