How railwayapp/railpack works
Main Components
• CLI Frontend (cmd/cli): the user‑facing binary (railpack) that parses commands, loads configuration (mise.toml), and dispatches build actions.
• Core Engine (core/…): orchestrates detection, build‑plan generation, templating, and logging. Key sub‑modules:
– Resolver: detects project language & versions.
– Generate: builds an abstract BuildPlan (steps, layers, commands).
– Plan: defines step ordering, caching, filters.
– Providers: language‑specific logic (node, python, java, etc.) plugged into Generate & Plan.
• BuildKit Interface (buildkit/…): translates the abstract BuildPlan into a BuildKit LLB (low‑level build) graph and executes it, producing image layers.
• Images & Docker Integration: Dockerfiles directory, local Docker daemon (or remote registry) for final image build/push.
• Docs Site (docs/…): an Astro/React static site that serves as user documentation (separate deployment).
• CI/CD & Releases (.github/, goreleaser.yml, Dockerfiles/): pipelines that test, build, package, and release binaries and Docker images.
Relationships & Data Flow
• User invokes railpack CLI → CLI Frontend
→ reads mise.toml / command‑line flags
→ calls Core Engine (Resolver → Generate → Plan)
→ passes BuildPlan to BuildKit Interface
→ BuildKit Interface constructs LLB graph, communicates with BuildKit daemon
→ Docker daemon builds image layers → final image pushed to registry or saved locally
• Providers plug into Core Engine: each language/provider module registers detection rules and build‑step builders.
• Docs Site is built & deployed separately (Astro → static assets → hosting).
• CI workflows run tests against Core, BuildKit, CLI, integration tests, and deploy releases via GoReleaser and Dockerfiles.
Architectural Patterns
• Plugin‑style providers: Core’s Generate & Plan modules load language‑specific “providers” for extensibility.
• Graph‑based build: abstract BuildPlan → directed acyclic graph (DAG) → LLB graph → container image layers.
• Layer‑caching & parallel steps via BuildKit.
• Separation of concerns: CLI (presentation), Core (business logic), BuildKit (execution engine).