Fast Dev Reload
In dev mode (openrun app create --dev), OpenRun watches the app source and reloads the app on changes. For containerized apps, with Fast dev reload, the dev image is built once, the app source directory is bind mounted into the container and a source change just restarts the container (or does nothing, for frameworks with built-in hot reload). Reload times become independent of the image build time.
This page covers how it works, the dev stage convention for custom Containerfiles, auto-inference when there is no dev stage, the explicit dev settings and toolchain caches.
How it works
- The dev image is built with
docker build --target <stage>, so the build stops at the dev stage (the stage that still has the toolchain) instead of the final runtime stage. - The image is rebuilt only when its identity changes: the Containerfile contents, build args, target stage or the contents of the configured
env_files(dependency manifests likerequirements.txt). Ordinary source changes never rebuild the image. - The app source is bind mounted over the configured directory inside the container, shadowing the copy baked into the image.
- On a source change, the container is restarted with no grace period (
reload: restart), recreated (reload: recreate) or left alone (reload: none, for frameworks like Flask/uvicorn that watch for changes themselves).
All app specs shipped with OpenRun configure this per framework, so spec-based apps get fast reload automatically. For apps that bring their own Containerfile, OpenRun infers the settings as described below.
The dev stage convention
The recommended way to enable fast reload for a custom Containerfile is to add one stage named dev, anywhere except last, whose CMD is the command that runs the app from source:
FROM golang:1.24 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o app ./cmd/app
FROM builder AS dev
CMD go run ./cmd/app
FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/app .
ENTRYPOINT ["/app/app"]Nothing else is needed, no changes in app.star. In dev mode, OpenRun builds the dev stage, mounts the source at the stage’s WORKDIR (/app here, inherited from builder) and runs the stage’s CMD. Editing a source file restarts the container and go run picks up the change.
The dev stage costs production builds nothing: builds without --target build the last stage, and BuildKit/buildah skip stages that the last stage does not depend on.
Notes:
- The dev stage must define
CMD(orENTRYPOINT); otherwise the app load fails, since the base image’s default command would not run the app. - If the stage’s base image defines its own
ENTRYPOINT, theCMDbecomes its arguments; addENTRYPOINT []in the dev stage to reset it.
dev stage placed last would silently become the production image; OpenRun rejects prod deployments of such a Containerfile and warns in dev mode.Auto-inference
When the Containerfile has no dev stage, OpenRun attempts to infer the dev settings (this is enabled by default; set disable to opt out):
| Containerfile | Dev image | Command | Source mounted at |
|---|---|---|---|
| Multi-stage build | The penultimate stage (typically the builder stage, which has the toolchain) | The final stage’s ENTRYPOINT/CMD, run in the dev image. If the penultimate stage defines its own CMD/ENTRYPOINT, that runs instead | The penultimate stage’s WORKDIR |
| Compiled app (build artifact) | The penultimate stage | The build is replayed, then the entry command runs; see below | The penultimate stage’s WORKDIR |
| Single-stage build | The full image, built once | Its own entry command | The WORKDIR |
Multi-stage builds:
ENVvalues declared in the final stage (with build arg defaults applied) are passed to the dev container, since the built dev image does not include them.Single-stage builds: since a single-stage image typically has the full toolchain, this gives interpreted apps (Python, Node) fast reload with zero configuration.
Compiled apps, build replay: when the entry command runs a build artifact (a file the final stage takes from the build stage with
COPY --from, like a Go binary or a jar), running it directly would fail: the artifact was produced under the source directory during the image build, and the source mount shadows it. OpenRun instead replays the build: the dev command becomes the build stage’sRUNinstructions after the sourceCOPY, followed by the entry command, e.g.go build -o app ./cmd/app && exec /app/app -flag value
Build replay details
- Artifact paths that the final stage renamed are rewritten to their build stage locations (
app.jar→/build/target/app-1.0.jar), including references insidesh -ccommand strings and files provided by directory copies. - Files the final stage copies from the build context (like an entrypoint script) are used from the mounted source.
- Dependency steps that run before the source
COPY(go mod download,mvn dependency:go-offline) are not repeated; they are baked into the dev image. RUN --mount=type=cachecache directories are automatically turned into named volumes so builds stay incremental across reloads.- Each reload re-runs the build step, which is exactly what a compiled language needs. The build writes its artifacts into the mounted source directory on the host (the same paths the image build produces).
Anything that cannot be inferred or safely replayed (no named build stage, no entry command, no WORKDIR, artifact built by steps that cannot be replayed) makes the app fall back to the rebuild-on-change flow. When an auto-inferred command fails to start or fails its health check, the error shows the inferred command and how to override it.
Auto-inference can still be semantically wrong, for example when the image build does codegen whose outputs live under the source directory, or the final stage installs runtime packages the build stage lacks. The dev stage convention is the explicit answer for those cases (or disable: True to opt out).
Configuring dev settings
Everything inferred can also be set explicitly via dev_settings in container.config in app.star. Explicit values always win over inferred ones:
container=container.config(container.AUTO, port=8000,
dev_settings={
"target": "builder", # Containerfile stage to build for dev
"command": "go run ./cmd/app",# command to run the app from source
"dir": "/app", # where the source is mounted (default: the stage's WORKDIR)
"reload": "restart", # restart (default) | none | recreate
"env_files": ["go.mod", "go.sum"], # changes to these rebuild the dev image
"additional_mounts": ["go-mod-cache:/go/pkg/mod", "go-build-cache:/root/.cache/go-build"],
"port": 8000, # dev command port, if different from the image port
"dev_stage": "dev", # stage name for the dev stage convention (default "dev")
"disable": False, # True switches back to the rebuild-on-change flow
})| Setting | Default | Meaning |
|---|---|---|
target | The dev_stage stage if present, else the penultimate stage | The Containerfile stage built for dev mode (docker build --target) |
command | The dev stage’s CMD, or the final stage’s entry command under auto-inference | The app start command, run with sh -c, overriding the image entrypoint |
dir | The effective WORKDIR of the dev stage | Absolute path where the app source is bind mounted, also the working directory |
reload | restart | What a source change does. restart restarts the container; none leaves it running, for dev servers with built-in hot reload; recreate removes and recreates the container |
env_files | Files whose content changes trigger a dev image rebuild and container recreate: dependency manifests like requirements.txt, pyproject.toml, pom.xml | |
additional_mounts | Extra named volume mounts, typically toolchain caches (Go module cache, Maven ~/.m2) so restarts stay fast | |
port | The port the built image uses | The port the dev command listens on, when different |
dev_stage | dev | The stage name used by the dev stage convention. Setting it to a name that does not exist in the Containerfile fails the app load |
disable | False | True disables fast dev reload and returns to rebuilding the image on every change |
Toolchain caches
Compiled languages benefit from persisting the toolchain caches across container recreates, using named volumes in additional_mounts. For the Go example above:
dev_settings={
"additional_mounts": ["go-mod-cache:/go/pkg/mod", "go-build-cache:/root/.cache/go-build"],
}With the mod and build caches on named volumes, a go run after a restart recompiles only the changed packages.