dockerfile is built from the project’s own Dockerfile instead of the Node.js
build. Use it for a service in any language (Python, Go, Ruby, Java, Rust, PHP, .NET…), or for a
Node.js app that needs system packages the Node.js image doesn’t have.
A Node.js app that the regular build can run should stay a Node.js service, even if it has a
Dockerfile: that build needs no Dockerfile upkeep and serves static directories.
The file
modelence.config.json
dockerfileis relative toroot(default".", the project root), androotis the build context: the build sees only the files under it. For a service inservices/api/with its Dockerfile there, set"root": "services/api"and"dockerfile": "Dockerfile".portslists the ports the process listens on, main port first, default[3000]. See Ports.image,buildandstaticcan’t be used withdockerfile: the Dockerfile defines the image and the build.
What the Dockerfile must do
- Listen on
0.0.0.0on the service’s ports. Traffic and the health check come from outside the container, so a process bound to127.0.0.1(the default ofuvicorn,gunicornandflask run) never receives them. The container gets the main port asPORT. Either readPORT, or listen on a fixed port and list it first inports. - Start the process with
CMDorENTRYPOINT. The image runs as the Dockerfile leaves it:ENTRYPOINT,CMD,USERandWORKDIRapply. Setstartin the file only to replace them; its commands run under/bin/sh -c. - Stop on
SIGTERM. A stopping container getsSIGTERM, thenSIGKILLafterstopTimeoutseconds (default 30). Use the exec form (CMD ["uvicorn", ...]), orexecin a shell form, so the signal reaches the process and not a shell in front of it. Requests can still arrive for about 10 seconds afterSIGTERM, so a server that must not drop any keeps serving that long before it exits, with astopTimeoutlonger than that wait. SeestopTimeout. - Pull base images from the mirror. Docker Hub limits how often images can be pulled, so a
build can fail on
FROM python:3.13-slim. Use the same image frompublic.ecr.aws/docker/library/, for exampleFROM public.ecr.aws/docker/library/python:3.13-slim. - Keep the build context small. Add a
.dockerignoreinrootfor.git, dependency folders (node_modules,.venv), build output and local.envfiles.
USER.
Variables at runtime
The container gets the same variables as any service, set in its environment at start:MONGODB_URI,
SITE_URL, PORT, the dashboard’s variables and the outputs env ties to resources. See
Variables. Read them from the environment as usual, such as
os.environ["DATABASE_URL"] in Python.
Variables in the build
A variable scoped to the build ("scopes": ["build", "runtime"]) reaches a Dockerfile in one of two
ways.
A value written in the file arrives as a build argument. Declare it with ARG before use:
RUN step that needs it:
USER instruction, add the user’s id to the mount, such
as --mount=type=secret,id=modelence-build-env,uid=1000.
Health checks
By default a container is healthy once something accepts connections on its port ({ "type": "tcp" }). Use { "type": "http", "path": "/health" } for an app with a health
endpoint, and { "type": "none" } for a process that listens on no port, such as a queue worker. See
Health checks.
Running it locally
modelence dev runs the service’s dev commands on the local machine, not in Docker, with the
connected environment’s variables. A project without a package.json needs dev set, for example
"dev": { "commands": ["uvicorn main:app --reload --port 8000"] }.
Writing a Dockerfile
When a project has no Dockerfile, write one inroot. Follow these rules:
- Start from the official image for the language, from the mirror, at the version the project
declares (
.python-version,pyproject.toml,go.mod,.ruby-version,pom.xml). - Copy the dependency manifest first and install, then copy the rest of the source, so a change to the code doesn’t reinstall the dependencies.
- Install with the project’s lockfile when it has one (
uv sync --frozen,poetry install,go mod download,bundle install). - Start a production server, not a development one:
gunicornoruvicornwithout--reload, notflask runormanage.py runserver. - Add a
.dockerignore.
ports names:
Dockerfile
modelence.config.json
gunicorn <project>.wsgi --bind 0.0.0.0:8000 instead. Add the environment’s host to
ALLOWED_HOSTS, for example from SITE_URL.
Go, built in one stage and run from a small image in a second. The program reads PORT:
Dockerfile
modelence.config.json
modelence.config.json
"rollout": "recreate" stops the old container before the new one starts, so
two versions never take the same jobs. A worker usually runs next to a web service; see
Multiple services.
Verifying the build
Build and run the image locally before deploying, with the same context and main port:http://localhost:<port>, and that the health check path, if set, answers
2xx. If Docker isn’t installed, tell the user that the image was not checked locally.