Developer docs / AI Fabric tutorials
Build your image from a Dockerfile
- Image DSL
The AI Fabric image DSL (.pip_install, .apt_install, .env, .run_commands) covers most images, but sometimes you already have a Dockerfile: one your team maintains, one shipped by an upstream project, or one that needs things the DSL doesn't express (COPYing local files into the image, ARG-parameterized bases, multi-stage builds). bladekit.Image.from_dockerfile(...) takes that Dockerfile as-is and builds it on AI Fabric's builders, the equivalent of Modal's Image.from_dockerfile.
In this tutorial you'll build an image from a small Dockerfile that installs pinned requirements and bakes a static asset into the filesystem via COPY, then run a function on it. Along the way you'll see how the build context works and what AI Fabric adds on top of your final stage.
Before you start
You need the AI Fabric CLI installed and authenticated (blade setup); no GPU is required. Your local Python should be 3.12, to match the Dockerfile's final stage (python:3.12-slim), since AI Fabric ships your function with cloudpickle.
Write the Dockerfile and its context
A Dockerfile build has two inputs: the Dockerfile itself, and the build context, the directory that COPY/ADD paths resolve against. Put both in a docker/ folder next to your script:
ARG PYTHON_VERSION=3.12
FROM python:${PYTHON_VERSION}-slim
# Your existing requirements file, resolved from the build context.
COPY requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt
# Bake static assets straight into the image filesystem.
COPY banner.txt /assets/banner.txt
ENV BANNER_PATH=/assets/banner.txtcowsay==6.1Baked into the image by YOUR Dockerfile Point from_dockerfile at it
In your script, build the image with from_dockerfile. context_dir= is required as soon as the Dockerfile reads from the context (our two COPY lines): AI Fabric packs the directory (honoring a .dockerignore at its root, 256 MiB compressed max) and uploads it with the build. Uploads are content-addressed: an unchanged context is deduplicated server-side, so re-runs upload nothing. build_args fills the Dockerfile's ARGs and is part of the image identity:
import pathlib
import bladekit
app = bladekit.app("dockerfile-image")
ctx = pathlib.Path(__file__).parent / "docker"
# Build the image from the Dockerfile on AI Fabric's builders. context_dir is the
# directory COPY paths resolve against (a .dockerignore at its root is
# honored). IMPORTANT: the final stage's Python must match your LOCAL Python
# (cloudpickle): python:3.12-slim matches a 3.12 client.
image = bladekit.Image.from_dockerfile(
ctx / "Dockerfile",
context_dir=ctx,
build_args={"PYTHON_VERSION": "3.12"},
)The usual layer methods still chain on top: from_dockerfile(...).pip_install("fastapi").env({"A": "b"}) applies after your Dockerfile's last instruction, with the same per-layer build cache.
Run a function on it
Now prove all three mechanisms in one function: cowsay was installed by your RUN pip install, the banner file was COPYed from your context, and BANNER_PATH was set by your ENV:
@app.function(image=image)
def shout(name: str) -> str:
import os
import pathlib
import cowsay # installed by YOUR Dockerfile's RUN pip install
banner = pathlib.Path(os.environ["BANNER_PATH"]).read_text().strip()
return cowsay.get_output_string("cow", f"{banner}, hello {name}!")
@app.local_entrypoint()
def main():
print(shout.remote("AI Fabric"))Run it
blade run dockerfile_image.pyThe first run uploads the context, builds the image (you'll see a single collapsed building line; add --verbose for the raw BuildKit steps, or blade image logs -f <build_id> to tail them), pushes it, and runs the function. The image is identified by a hash of the Dockerfile text, the build_args, and the context content. Change any of them and AI Fabric rebuilds exactly what changed; change nothing and re-runs skip the build entirely.
_______________________________________________________
| Baked into the image by YOUR Dockerfile, hello AI Fabric! |
=======================================================
\
\
^__^
(oo)\_______
(__)\ )\/\When to use which
Rule of thumb: start from_catalog (curated CUDA/PyTorch bases), reach from_registry for any public image you extend with the DSL, and use from_dockerfile when the Dockerfile is the source of truth: existing Dockerfiles, COPYing local files, ARGs, or multi-stage builds. All three end in the same place: a cached, content-addressed image your functions cold-start from.
Take it for a spin
Everything above in one file, ready to run.
import pathlib
import bladekit
# In a real project docker/Dockerfile, docker/requirements.txt and
# docker/banner.txt are files you already have. This tutorial writes them so
# it stays a single runnable file. The AI Fabric part starts at from_dockerfile.
ctx = pathlib.Path(__file__).parent / "docker"
ctx.mkdir(exist_ok=True)
(ctx / "Dockerfile").write_text(
"""\
ARG PYTHON_VERSION=3.12
FROM python:${PYTHON_VERSION}-slim
# Your existing requirements file, resolved from the build context.
COPY requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt
# Bake static assets straight into the image filesystem.
COPY banner.txt /assets/banner.txt
ENV BANNER_PATH=/assets/banner.txt
"""
)
(ctx / "requirements.txt").write_text("cowsay==6.1\n")
(ctx / "banner.txt").write_text("Baked into the image by YOUR Dockerfile\n")
app = bladekit.app("dockerfile-image")
# Build the image from the Dockerfile on AI Fabric's builders. context_dir is the
# directory COPY paths resolve against (a .dockerignore at its root is
# honored). IMPORTANT: the final stage's Python must match your LOCAL Python
# (cloudpickle): python:3.12-slim matches a 3.12 client.
image = bladekit.Image.from_dockerfile(
ctx / "Dockerfile",
context_dir=ctx,
build_args={"PYTHON_VERSION": "3.12"},
)
@app.function(image=image)
def shout(name: str) -> str:
import os
import pathlib
import cowsay # installed by YOUR Dockerfile's RUN pip install
banner = pathlib.Path(os.environ["BANNER_PATH"]).read_text().strip()
return cowsay.get_output_string("cow", f"{banner}, hello {name}!")
@app.local_entrypoint()
def main():
print(shout.remote("AI Fabric"))Concepts used: Image build, Run