Add railpack integration: rp_plan, rp_build, detect_app fallback

claude · claude · commit 6fecb7d65d11 · 2026-03-30T06:00:08.000Z
Adds two new public functions and extends detect_app: - rp_plan(path): run `railpack plan` and return parsed build plan dict - rp_build(path, tag, buildkit_host, config): build via railpack + BuildKit, supporting PHP, Java, Ruby, .NET, Elixir, Deno, C++, Gleam and more - detect_app gains use_railpack=False: falls back to rp_build for unknown stacks Includes install instructions (mise/brew/binary/scoop) and BuildKit setup, plus examples in index.ipynb and README: apt package deps, custom build commands, and the hybrid workflow (dockeasy generates Dockerfile, railpack builds it). https://claude.ai/code/session_012RMjKQkcXoWnEkDF29rEGR
diff --git a/README.md b/README.md
@@ -252,6 +252,65 @@ for files, label in cases:
     package.json + pyproject.toml → fastapi_react
     pyproject.toml → python_app (port 8000)
 
+### Railpack: build any language
+
+[Railpack](https://railpack.com) is Railway's zero-config image builder. Where
+`detect_app` covers Python, Go, Rust and Node, railpack adds **PHP, Java, Ruby,
+.NET, Elixir, Deno, C++, Gleam** and more — and builds via BuildKit LLB, so no
+Dockerfile is required. It also detects an existing `Dockerfile` in the repo and
+uses it directly.
+
+**Install railpack**
+
+| Platform | Command |
+|---|---|
+| macOS / Linux (mise) | `curl https://mise.run \| sh && mise install github:railwayapp/railpack@latest` |
+| macOS (Homebrew) | `brew install railpack` |
+| Linux (binary) | `curl -L .../railpack-linux-amd64 -o railpack && chmod +x railpack && sudo mv railpack /usr/local/bin/` |
+| Windows (Scoop) | `scoop install railpack` |
+
+**Start BuildKit** (required for `rp_build`):
+
+``` bash
+docker run --rm --privileged -d --name buildkit moby/buildkit
+export BUILDKIT_HOST='docker-container://buildkit'
+```
+
+``` python
+# Build a Laravel (PHP) app — detect_app can't handle this, railpack can
+rp_build('/path/to/my-laravel-app', tag='myapp:latest')
+
+# detect_app with railpack fallback — no ValueError for unknown stacks
+detect_app('/path/to/my-java-app', use_railpack=True, tag='myapp:latest')
+
+# Inspect what railpack detects before building
+plan = rp_plan('/path/to/my-node-app')
+print(plan['deploy']['startCommand'])   # e.g. 'node dist/index.js'
+print(plan['packages'])                 # e.g. {'node': '20.x'}
+
+# Pass apt packages and custom commands — mirrors dockeasy's pkgs= pattern
+rp_build('.', tag='myapp:latest', config={
+    '$schema': 'https://schema.railpack.com',
+    'steps': {
+        'install': {'commands': ['apt-get install -y libpq-dev libgdal-dev']}
+    },
+    'deploy': {
+        'startCommand': 'gunicorn app:create_app --bind 0.0.0.0:8000 --workers 4',
+        'variables': {'DATABASE_POOL_SIZE': '10'}
+    }
+})
+
+# Hybrid: dockeasy generates the Dockerfile, railpack builds it via BuildKit
+df = python_app(port=8000, pkgs=['libpq-dev', 'curl'], vols=['/app/data'], healthcheck='/health')
+df.save('/path/to/myproject/Dockerfile')   # railpack auto-detects this
+rp_build('/path/to/myproject', tag='myapp:latest')
+
+# Or load an existing Dockerfile, extend it, then build with railpack
+df = Dockerfile.load('/path/to/myproject/Dockerfile')
+df.run('apt-get install -y libpq-dev').save('/path/to/myproject/Dockerfile')
+rp_build('/path/to/myproject', tag='myapp:v2')
+```
+
 ## Docker Compose
 
 The [`Compose`](https://Karthik777.github.io/dockeasy/core.html#compose)
diff --git a/dockeasy/core.py b/dockeasy/core.py
@@ -5,7 +5,7 @@
 # %% auto #0
 __all__ = ['fasthtml_app', 'mk_flags', 'Dockerfile', 'Cli', 'Docker', 'test', 'drun', 'containers', 'images', 'stop', 'logs',
            'rm', 'rmi', 'dict2str', 'service', 'Compose', 'python_app', 'fastapi_react', 'go_app', 'rust_app',
-           'node_app', 'detect_app', 'env_set', 'env_get', 'secret_set', 'secret_get', 'secrets']
+           'node_app', 'detect_app', 'rp_plan', 'rp_build', 'env_set', 'env_get', 'secret_set', 'secret_get', 'secrets']
 
 # %% ../nbs/00_core.ipynb #c7b52454175ab4d4
 import re, json, os, yaml, keyring, time
@@ -349,8 +349,8 @@ def node_app(port=3000, node_version='20', cmd=None, build_cmd='npm run build',
 
 fasthtml_app = bind(python_app, port=5001, cmd=['python', 'app.py'], multistage=False)
 
-def detect_app(path='.', multistage=True, **kw):
-    'A naive project type detector from path and return the appropriate Dockerfile. for **kw lookup other app builders'
+def detect_app(path='.', multistage=True, use_railpack=False, **kw):
+    'Detect project type and return the appropriate Dockerfile. use_railpack=True falls back to rp_build() for unsupported stacks (PHP, Java, Ruby, .NET, Elixir, Deno, C++ etc.) — returns tag str instead of Dockerfile in that case. For **kw see each app builder.'
     p = Path(path)
     has = lambda f: (p/f).exists()
     read = lambda f: (p/f).read_text().lower() if has(f) else ''
@@ -363,7 +363,35 @@ def detect_app(path='.', multistage=True, **kw):
     if pyp and 'python-fasthtml' in read('pyproject.toml'): return fasthtml_app(multistage=multistage, **kw)
     if pyp: return python_app(multistage=multistage, **kw)
     if req: return python_app(multistage=False, req=True, **kw)
-    raise ValueError(f'Cannot detect project type in {path!r}')
+    if use_railpack: return rp_build(path=path, **kw)
+    raise ValueError(f'Cannot detect project type in {path!r}. Try use_railpack=True for PHP, Java, Ruby, .NET, Elixir, Deno etc.')
+
+# %% ../nbs/00_core.ipynb #q08mqwq7vu
+def rp_plan(path='.'):
+    'Run `railpack plan` on path and return the parsed build plan dict. Useful for inspecting detected language, packages, and build steps without building.'
+    result = run('railpack', 'plan', str(Path(path).resolve()))
+    return json.loads(result)
+
+def rp_build(path='.', tag=None, buildkit_host=None, config=None):
+    'Build image from path using railpack + BuildKit. Supports all railpack-detected languages (PHP, Java, Ruby, .NET, Elixir, Deno, C++ etc.). config dict is written as railpack.json if one does not already exist. Returns tag.'
+    import subprocess
+    p = Path(path).resolve()
+    cfg_path = p / 'railpack.json'
+    wrote_cfg = False
+    if config and not cfg_path.exists():
+        cfg_path.write_text(json.dumps(config, indent=2))
+        wrote_cfg = True
+    try:
+        args = ['railpack', 'build']
+        if tag: args += ['--tag', tag]
+        args.append(str(p))
+        env = os.environ.copy()
+        if buildkit_host: env['BUILDKIT_HOST'] = buildkit_host
+        res = subprocess.run(args, env=env, capture_output=True)
+        if res.returncode: raise IOError((res.stdout + b' ;; ' + res.stderr).decode().strip())
+    finally:
+        if wrote_cfg: cfg_path.unlink(missing_ok=True)
+    return tag
 
 # %% ../nbs/00_core.ipynb #5f5a4229dae3d2c4
 _FASTOPS_ENV = Path.home() / '.config' / 'fastops' / '.env'
diff --git a/nbs/00_core.ipynb b/nbs/00_core.ipynb
@@ -1116,7 +1116,21 @@
    "id": "e17b41b26d006536",
    "metadata": {},
    "outputs": [],
-   "source": "#| export\ndef python_app(port=8000, cmd=None, im='python:3.13-slim', wd='/app', pkgs=None,\n    vols=None, multistage=True, uv_image='ghcr.io/astral-sh/uv:python3.13-bookworm', healthcheck=None, req=False):\n    'Python app Dockerfile. multistage=True (default): uv-builder → slim. False: single-stage with uv binary copy. req=True: use requirements.txt instead of pyproject.toml (forces multistage=False).'\n    if multistage:\n        df = Dockerfile().with_uv(uv_image, im, wd).copy(wd, wd, from_='builder').env('PATH', f'{wd}/.venv/bin:$PATH').packages(*listify(pkgs))\n    else: df = Dockerfile().from_(im).workdir(wd).packages(*listify(pkgs)).inst_uv(req=req, wd=wd).copy('.', '.')\n    if vols: df = df.run('mkdir -p ' + ' '.join(listify(vols)))\n    if healthcheck: df = df.healthcheck(f'curl -f http://localhost:{port}{healthcheck}', i='30s', t='5s', r='3')\n    _cmd = cmd or ['python', 'main.py']\n    return df.expose(port).cmd(_cmd if isinstance(_cmd, list) else _cmd.split())\n\ndef fastapi_react(port=8000, node_version='20', frontend_dir='frontend', build_dir='dist',\n    image='python:3.13-slim', pkgs=None, healthcheck='/health', multistage=False,\n    uv_image='ghcr.io/astral-sh/uv:python3.13-bookworm'):\n    'Two-stage (default) or three-stage (multistage=True) Dockerfile: Node.js frontend + Python/FastAPI backend'\n    df = (Dockerfile().from_(f'node:{node_version}-slim', as_='frontend')\n          .workdir('/build').copy(f'{frontend_dir}/package*.json', '.')\n          .run('npm ci').copy(frontend_dir, '.').run('npm run build'))\n    if multistage: df = df.with_uv(uv_image, image, '/app').copy('/app', '/app', from_='builder').env('PATH', '/app/.venv/bin:$PATH').packages(*listify(pkgs))\n    else: df = df.from_(image).workdir('/app').packages(*listify(pkgs)).inst_uv(wd='/app').copy('.', '.')\n    df = df.copy(f'/build/{build_dir}', '/app/static', from_='frontend')\n    if healthcheck: df = df.healthcheck(f'curl -f http://localhost:{port}{healthcheck}', i='30s', t='5s', r='3')\n    return df.expose(port).cmd(['uvicorn', 'main:app', '--host', '0.0.0.0', f'--port={port}'])\n\ndef go_app(port=8080, go_version='1.22', binary='app', runtime='gcr.io/distroless/static', cmd=None, cgo=False):\n    'Two-stage Go Dockerfile: go compiler + go mod cache → distroless runtime'\n    df = (Dockerfile().from_(f'golang:{go_version}-alpine', as_='builder')\n          .workdir('/src').copy('go.mod', '.').copy('go.sum', '.')\n          .run_mount('go mod download', target='/go/pkg/mod')\n          .copy('.', '.').env('CGO_ENABLED', '0' if not cgo else '1')\n          .run(f'go build -ldflags=\"-s -w\" -o /{binary} .').from_(runtime)\n          .copy(f'/{binary}', f'/{binary}', from_='builder').expose(port))\n    return df.cmd(cmd or [f'/{binary}'])\n\ndef rust_app(port=8080, rust_version='1', binary='app', runtime='gcr.io/distroless/static', features=None):\n    'Two-stage Rust Dockerfile: cargo build --release → distroless runtime'\n    build_cmd = 'cargo build --release' + (f' --features {features}' if features else '')\n    df = (Dockerfile().from_(f'rust:{rust_version}-slim-bookworm', as_='builder').workdir('/src')\n          .copy('.', '.').run_mount(build_cmd, target='/usr/local/cargo/registry').from_(runtime)\n          .copy(f'/src/target/release/{binary}', f'/{binary}', from_='builder').expose(port))\n    return df.cmd([f'/{binary}'])\n\ndef node_app(port=3000, node_version='20', cmd=None, build_cmd='npm run build', static=False):\n    'Node.js Dockerfile. static=True does two-stage build → serve dist/; False runs node directly.'\n    df = (Dockerfile().from_(f'node:{node_version}-slim', as_='builder' if static else None)\n          .workdir('/app').copy('package*.json', '.').run('npm ci').copy('.', '.'))\n    if static:\n        return (df.run(build_cmd).from_(f'node:{node_version}-slim').workdir('/app')\n                .run('npm install -g serve').copy('/app/dist', '.', from_='builder')\n                .expose(port).cmd(cmd or ['serve', '-s', '.', '-l', str(port)]))\n    return df.expose(port).cmd(cmd or ['node', 'index.js'])\n\nfasthtml_app = bind(python_app, port=5001, cmd=['python', 'app.py'], multistage=False)\n\ndef detect_app(path='.', multistage=True, **kw):\n    'A naive project type detector from path and return the appropriate Dockerfile. for **kw lookup other app builders'\n    p = Path(path)\n    has = lambda f: (p/f).exists()\n    read = lambda f: (p/f).read_text().lower() if has(f) else ''\n    pyp, req= has('pyproject.toml'), has('requirements.txt')\n    has_py = pyp or req\n    if has('Cargo.toml'): return rust_app(**kw)\n    if has('go.mod'): return go_app(**kw)\n    if has('package.json') and has_py: return fastapi_react(multistage=multistage, **kw)\n    if has('package.json'): return node_app(**kw)\n    if pyp and 'python-fasthtml' in read('pyproject.toml'): return fasthtml_app(multistage=multistage, **kw)\n    if pyp: return python_app(multistage=multistage, **kw)\n    if req: return python_app(multistage=False, req=True, **kw)\n    raise ValueError(f'Cannot detect project type in {path!r}')"
+   "source": "#| export\ndef python_app(port=8000, cmd=None, im='python:3.13-slim', wd='/app', pkgs=None,\n    vols=None, multistage=True, uv_image='ghcr.io/astral-sh/uv:python3.13-bookworm', healthcheck=None, req=False):\n    'Python app Dockerfile. multistage=True (default): uv-builder → slim. False: single-stage with uv binary copy. req=True: use requirements.txt instead of pyproject.toml (forces multistage=False).'\n    if multistage:\n        df = Dockerfile().with_uv(uv_image, im, wd).copy(wd, wd, from_='builder').env('PATH', f'{wd}/.venv/bin:$PATH').packages(*listify(pkgs))\n    else: df = Dockerfile().from_(im).workdir(wd).packages(*listify(pkgs)).inst_uv(req=req, wd=wd).copy('.', '.')\n    if vols: df = df.run('mkdir -p ' + ' '.join(listify(vols)))\n    if healthcheck: df = df.healthcheck(f'curl -f http://localhost:{port}{healthcheck}', i='30s', t='5s', r='3')\n    _cmd = cmd or ['python', 'main.py']\n    return df.expose(port).cmd(_cmd if isinstance(_cmd, list) else _cmd.split())\n\ndef fastapi_react(port=8000, node_version='20', frontend_dir='frontend', build_dir='dist',\n    image='python:3.13-slim', pkgs=None, healthcheck='/health', multistage=False,\n    uv_image='ghcr.io/astral-sh/uv:python3.13-bookworm'):\n    'Two-stage (default) or three-stage (multistage=True) Dockerfile: Node.js frontend + Python/FastAPI backend'\n    df = (Dockerfile().from_(f'node:{node_version}-slim', as_='frontend')\n          .workdir('/build').copy(f'{frontend_dir}/package*.json', '.')\n          .run('npm ci').copy(frontend_dir, '.').run('npm run build'))\n    if multistage: df = df.with_uv(uv_image, image, '/app').copy('/app', '/app', from_='builder').env('PATH', '/app/.venv/bin:$PATH').packages(*listify(pkgs))\n    else: df = df.from_(image).workdir('/app').packages(*listify(pkgs)).inst_uv(wd='/app').copy('.', '.')\n    df = df.copy(f'/build/{build_dir}', '/app/static', from_='frontend')\n    if healthcheck: df = df.healthcheck(f'curl -f http://localhost:{port}{healthcheck}', i='30s', t='5s', r='3')\n    return df.expose(port).cmd(['uvicorn', 'main:app', '--host', '0.0.0.0', f'--port={port}'])\n\ndef go_app(port=8080, go_version='1.22', binary='app', runtime='gcr.io/distroless/static', cmd=None, cgo=False):\n    'Two-stage Go Dockerfile: go compiler + go mod cache → distroless runtime'\n    df = (Dockerfile().from_(f'golang:{go_version}-alpine', as_='builder')\n          .workdir('/src').copy('go.mod', '.').copy('go.sum', '.')\n          .run_mount('go mod download', target='/go/pkg/mod')\n          .copy('.', '.').env('CGO_ENABLED', '0' if not cgo else '1')\n          .run(f'go build -ldflags=\"-s -w\" -o /{binary} .').from_(runtime)\n          .copy(f'/{binary}', f'/{binary}', from_='builder').expose(port))\n    return df.cmd(cmd or [f'/{binary}'])\n\ndef rust_app(port=8080, rust_version='1', binary='app', runtime='gcr.io/distroless/static', features=None):\n    'Two-stage Rust Dockerfile: cargo build --release → distroless runtime'\n    build_cmd = 'cargo build --release' + (f' --features {features}' if features else '')\n    df = (Dockerfile().from_(f'rust:{rust_version}-slim-bookworm', as_='builder').workdir('/src')\n          .copy('.', '.').run_mount(build_cmd, target='/usr/local/cargo/registry').from_(runtime)\n          .copy(f'/src/target/release/{binary}', f'/{binary}', from_='builder').expose(port))\n    return df.cmd([f'/{binary}'])\n\ndef node_app(port=3000, node_version='20', cmd=None, build_cmd='npm run build', static=False):\n    'Node.js Dockerfile. static=True does two-stage build → serve dist/; False runs node directly.'\n    df = (Dockerfile().from_(f'node:{node_version}-slim', as_='builder' if static else None)\n          .workdir('/app').copy('package*.json', '.').run('npm ci').copy('.', '.'))\n    if static:\n        return (df.run(build_cmd).from_(f'node:{node_version}-slim').workdir('/app')\n                .run('npm install -g serve').copy('/app/dist', '.', from_='builder')\n                .expose(port).cmd(cmd or ['serve', '-s', '.', '-l', str(port)]))\n    return df.expose(port).cmd(cmd or ['node', 'index.js'])\n\nfasthtml_app = bind(python_app, port=5001, cmd=['python', 'app.py'], multistage=False)\n\ndef detect_app(path='.', multistage=True, use_railpack=False, **kw):\n    'Detect project type and return the appropriate Dockerfile. use_railpack=True falls back to rp_build() for unsupported stacks (PHP, Java, Ruby, .NET, Elixir, Deno, C++ etc.) — returns tag str instead of Dockerfile in that case. For **kw see each app builder.'\n    p = Path(path)\n    has = lambda f: (p/f).exists()\n    read = lambda f: (p/f).read_text().lower() if has(f) else ''\n    pyp, req= has('pyproject.toml'), has('requirements.txt')\n    has_py = pyp or req\n    if has('Cargo.toml'): return rust_app(**kw)\n    if has('go.mod'): return go_app(**kw)\n    if has('package.json') and has_py: return fastapi_react(multistage=multistage, **kw)\n    if has('package.json'): return node_app(**kw)\n    if pyp and 'python-fasthtml' in read('pyproject.toml'): return fasthtml_app(multistage=multistage, **kw)\n    if pyp: return python_app(multistage=multistage, **kw)\n    if req: return python_app(multistage=False, req=True, **kw)\n    if use_railpack: return rp_build(path=path, **kw)\n    raise ValueError(f'Cannot detect project type in {path!r}. Try use_railpack=True for PHP, Java, Ruby, .NET, Elixir, Deno etc.')"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "wcnw7e3kg8",
+   "source": "## Railpack integration\n\n[Railpack](https://railpack.com) builds images via BuildKit LLB — no Dockerfile needed. It auto-detects 12+ languages including PHP, Java, Ruby, .NET, Elixir, Deno and more. Requires the `railpack` binary and a running BuildKit daemon.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "q08mqwq7vu",
+   "source": "#| export\ndef rp_plan(path='.'):\n    'Run `railpack plan` on path and return the parsed build plan dict. Useful for inspecting detected language, packages, and build steps without building.'\n    result = run('railpack', 'plan', str(Path(path).resolve()))\n    return json.loads(result)\n\ndef rp_build(path='.', tag=None, buildkit_host=None, config=None):\n    'Build image from path using railpack + BuildKit. Supports all railpack-detected languages (PHP, Java, Ruby, .NET, Elixir, Deno, C++ etc.). config dict is written as railpack.json if one does not already exist. Returns tag.'\n    import subprocess\n    p = Path(path).resolve()\n    cfg_path = p / 'railpack.json'\n    wrote_cfg = False\n    if config and not cfg_path.exists():\n        cfg_path.write_text(json.dumps(config, indent=2))\n        wrote_cfg = True\n    try:\n        args = ['railpack', 'build']\n        if tag: args += ['--tag', tag]\n        args.append(str(p))\n        env = os.environ.copy()\n        if buildkit_host: env['BUILDKIT_HOST'] = buildkit_host\n        res = subprocess.run(args, env=env, capture_output=True)\n        if res.returncode: raise IOError((res.stdout + b' ;; ' + res.stderr).decode().strip())\n    finally:\n        if wrote_cfg: cfg_path.unlink(missing_ok=True)\n    return tag",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
   },
   {
    "cell_type": "markdown",
@@ -1403,4 +1417,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}
diff --git a/nbs/index.ipynb b/nbs/index.ipynb
