docs: restructure runtime configuration and deprecate legacy formats by elijah-rou · Pull Request #262 · CerebriumAI/documentation

elijah-rou · 2026-01-21T15:38:18Z

Summary

Clarify that TOML entrypoint always takes precedence over Dockerfile CMD/ENTRYPOINT
Deprecate cerebrium.* prefix on all TOML sections (e.g., [cerebrium.deployment] → [deployment])
Move dependencies under runtime: [runtime.{type}.dependencies.*]
Replace [dependencies.paths] with _file_relative_path key inside dependency sections
Update all documentation examples across 40+ files to use the new format
Add backwards compatibility section to TOML reference documenting all deprecated patterns

Details

TOML prefix removal

All [cerebrium.*] section prefixes are deprecated. Sub-keys become top-level (e.g., [cerebrium.hardware] → [hardware]). Old format still works for backwards compatibility.

Runtime types

Runtime	Description
`[runtime.cortex]`	Default Cerebrium-managed Python runtime
`[runtime.python]`	Custom Python ASGI/WSGI web servers
`[runtime.docker]`	Custom Dockerfile deployments

Dependencies

Dependencies are now specified under the runtime section:

[runtime.cortex.dependencies.pip]
torch = "latest"
_file_relative_path = "requirements.txt"  # Optional: use a requirements file

The [dependencies.paths] section is replaced by _file_relative_path inside each dependency section.

Test plan

Verify all TOML examples in docs render correctly
Confirm deprecation notices display properly
Check that internal links remain valid

…rfile CMD - Add "Entrypoint Precedence" section to custom-dockerfiles.mdx explaining that cerebrium.toml entrypoint overrides Dockerfile CMD when specified - Update toml-reference.mdx to document dockerfile_path parameter and add entrypoint precedence info box - Clarify that either Dockerfile CMD or TOML entrypoint is required

Split runtime documentation into separate cortex, python, and docker sections. Update all examples to use new [cerebrium.runtime.cortex], [cerebrium.runtime.python], and [cerebrium.runtime.docker] configuration patterns. Add backwards compatibility notes for deprecated [cerebrium.runtime.custom] section.

…fix removal - Add deprecation notice for cerebrium.* prefix (new format removes prefix) - Update Dependencies section to show runtime-specific dependencies as recommended - Add deprecation warnings for top-level [cerebrium.dependencies.*] sections - Update complete examples to use runtime-specific dependencies - Add backwards compatibility section for dependency migration paths

…format - Add deprecation notice for cerebrium.* prefix in TOML sections - Update all documentation examples to use new format: - [cerebrium.deployment] → [deployment] - [cerebrium.runtime.*] → [runtime.*] - [cerebrium.hardware] → [hardware] - [cerebrium.scaling] → [scaling] - [cerebrium.dependencies.*] → [dependencies.*] - Update text references to match new format - The old format remains backwards compatible

- Rename runtime: cortex → auto-py, python stays as python - Rename TOML sections: [dependencies.*] → [deps.*] - Add deprecation notice for old runtime name cortex → auto-py - Update all prose references (Cortex runtime → auto-py runtime) - Old names remain backwards compatible

- Rename deps to dependencies in all examples - Replace [dependencies.paths] section with _file_relative_path key - Document file + inline dependency merging behavior - Update backwards compatibility section

…ement files - Revert deps → dependencies (dependencies is the correct name) - Replace [dependencies.paths] with _file_relative_path key inside dependency sections - Example: [dependencies.pip] with _file_relative_path = "requirements.txt"

- Revert all auto-py → cortex - Remove unnecessary deprecation notice for runtime name change - Keep cortex as the default runtime name

milo157 · 2026-01-29T17:35:34Z

cerebrium/container-images/custom-dockerfiles.mdx


 1. You must expose a port using the `EXPOSE` command - this port will be referenced later in your `cerebrium.toml` configuration
-2. A `CMD` command is required to specify what runs when the container starts (typically your server process)
+2. Either a `CMD` or `ENTRYPOINT` directive must be defined in your Dockerfile OR the `entrypoint` key in your `cerebrium.toml` under `[runtime.docker]`. This specifies what runs when the container starts. The TOML configuration will take precedence


The toml configuration, 'entrypoint', will take precedence

milo157 · 2026-01-29T17:36:35Z

cerebrium/container-images/custom-dockerfiles.mdx

 1. You must expose a port using the `EXPOSE` command - this port will be referenced later in your `cerebrium.toml` configuration
-2. A `CMD` command is required to specify what runs when the container starts (typically your server process)
+2. Either a `CMD` or `ENTRYPOINT` directive must be defined in your Dockerfile OR the `entrypoint` key in your `cerebrium.toml` under `[runtime.docker]`. This specifies what runs when the container starts. The TOML configuration will take precedence
 3. Set the working directory using `WORKDIR` to ensure your application runs from the correct location (defaults to root directory if not specified)


No WORKDIR in the dockerfile above? worth putting it in

milo157 · 2026-01-29T17:42:57Z

cerebrium/container-images/custom-web-servers.mdx

 readycheck_endpoint = "/ready"

-[cerebrium.dependencies.pip]
+[dependencies.pip]


not worth mentioning paths here to point to requirements.txt or apt dependancies. or a link to other parts of the doc to see

milo157 · 2026-01-29T17:44:27Z

cerebrium/container-images/custom-web-servers.mdx

 - `healthcheck_endpoint`: The endpoint used to confirm instance health. If unspecified, defaults to a TCP ping on the configured port. If the health check registers a non-200 response, it will be considered _unhealthy_, and be restarted should it not recover timely.
 - `readycheck_endpoint`: The endpoint used to confirm if the instance is ready to receive. If unspecified, defaults to a TCP ping on the configured port. If the ready check registers a non-200 response, it will not be a viable target for request routing.

+You can also configure build settings in the Python runtime section:


you mention built settings but where can i see an exhaustive list?

milo157 · 2026-01-29T17:52:07Z

cerebrium/container-images/defining-container-images.mdx

@@ -21,17 +21,17 @@ Check out the [Introductory Guide](/cerebrium/getting-started/introduction) for
 <Info>
  It is possible to initialize an existing project by adding a `cerebrium.toml`


Maybe we can word this better also make it more obvious instead of an info block but this is not the right please to put it. Maybe we put in the Getting started -> introduciton page about having an existing project

milo157 · 2026-01-29T18:20:42Z