Skip to content

feat: add support for user-configurable build methods and custom Dockerfile paths#2

Draft
freddyjaoko wants to merge 1 commit into
xt42io:mainfrom
freddyjaoko:feat/dockerfile-buildpath
Draft

feat: add support for user-configurable build methods and custom Dockerfile paths#2
freddyjaoko wants to merge 1 commit into
xt42io:mainfrom
freddyjaoko:feat/dockerfile-buildpath

Conversation

@freddyjaoko

@freddyjaoko freddyjaoko commented Jun 7, 2026

Copy link
Copy Markdown

Add Dockerfile build path alongside Railpack

Closes #1

Aeroplane previously only supported building via Railpack (BuildKit LLB). This PR adds a fully separate Dockerfile build path using docker build, so repos that ship their own Dockerfile now work without any workarounds.


What changed

Auto-detection

At deploy time, after the repo is cloned, Aeroplane checks for a Dockerfile in the app directory. If one is found and the service is still set to railpack, the build automatically switches to dockerfile mode — and that discovery is persisted to the database so the Settings tab reflects it on the next load.

Two build paths, one container runtime

clone repo
     │
     ├── Dockerfile detected / mode = "dockerfile"
     │       └── docker build -f Dockerfile -t <image> .   (DOCKER_BUILDKIT=1)
     │
     └── no Dockerfile / mode = "railpack"
             └── railpack build --name <image> ...
     │
     ▼
docker run <image>   ← identical from here on

Both paths produce the same tagged Docker image, so zero-downtime rollout, Caddy hot-reload, health probing, worker mode, and static site export are completely unchanged.

Build-arg passthrough

When building with a Dockerfile, service env vars are forwarded as --build-arg flags so ARG declarations in the Dockerfile can pick them up (same vars Railpack would receive).

BuildKit reuse

If BUILDKIT_HOST points to a TCP address (Aeroplane's embedded BuildKit daemon), docker build will use it via BUILDKIT_HOST env, keeping caching consistent.


Database migration

Two new columns are added to the projects table with safe ALTER TABLE … ADD COLUMN migrations (no destructive changes):

Column Type Default
build_method TEXT 'railpack'
dockerfile_path TEXT 'Dockerfile'

All existing services continue to use Railpack unless a Dockerfile is detected.


Settings UI

A Build method toggle appears in the service Settings tab for Git-backed services:

  • Railpack (default) — auto-detects language/framework, no Dockerfile needed
  • Dockerfile — runs docker build, bypasses Railpack entirely; exposes a Dockerfile path input for non-standard locations (e.g. docker/Dockerfile.prod)

A hint in Railpack mode explains the auto-detection behaviour.


What's explicitly NOT supported

Railpack does not support Dockerfiles internally (it uses BuildKit LLB directly). The two paths are mutually exclusive by design — switching to Dockerfile mode fully bypasses Railpack.


Testing checklist

  • Service with Dockerfile at root auto-switches on first deploy
  • Service without Dockerfile uses Railpack as before
  • Manual override to dockerfile in Settings is persisted and respected
  • Custom dockerfilePath (e.g. infra/Dockerfile) is respected
  • Build-args are forwarded correctly to ARG declarations in the Dockerfile
  • Zero-downtime swap, worker mode, and static sites still work post-build
  • Existing services are unaffected (migration defaults to railpack)

Summary by cubic

Adds user-selectable build methods (railpack or Dockerfile) with support for custom Dockerfile paths and automatic detection at deploy time. Repos with a Dockerfile now build via docker build while keeping the same image, rollout, and runtime behavior.

  • New Features

    • Auto-detect a Dockerfile on deploy; switch to dockerfile mode and persist it so Settings reflects the change.
    • Settings UI: Build method toggle and Dockerfile path input; hint explains auto-detect when in railpack mode.
    • Dockerfile builds use docker build with DOCKER_BUILDKIT=1; reuse external BuildKit when BUILDKIT_HOST is a TCP address.
    • Service env vars are forwarded as --build-arg so ARG values work in the Dockerfile.
    • Both build paths output the same tagged image; rollout, health checks, workers, and static export are unchanged.
    • API/DB: add buildMethod and dockerfilePath to service payloads; add build_method and dockerfile_path columns and defaults.
  • Migration

    • No breaking changes: defaults to railpack with dockerfilePath = Dockerfile.
    • Existing services stay on railpack; if a Dockerfile is present, the next deploy auto-switches and persists the mode.
    • To use a non-standard path, set dockerfilePath in Settings; if the path is invalid, the build will fail with guidance to update the path or switch back to railpack.

Written for commit fc3aa4a. Summary will update on new commits.

Review in cubic

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Dockerfile detection as an alternative build path

1 participant