App Author

An app blueprint describes an environment: its base image, application-owned packages, published commands, runtime mounts, workload, and install policy. Reploy owns resolution, image construction, validation, runtime wiring, and installation.

Smallest Blueprint

Only format identity, supported platforms, environment identity, and a base image are required:

blueprint:
  schema: 1
  version: 0.1.0
  compatibility:
    platforms: [linux/amd64, linux/arm64]

environment:
  id: example-app
  base:
    image: python:3.11-slim

This base-only form can be staged, built, inspected, installed, and opened with reploy shell. Add applications and commands only when the environment needs them.

Minimal Runnable Python App

blueprint:
  schema: 1
  version: 0.1.0
  compatibility:
    platforms: [linux/amd64, linux/arm64]

environment:
  id: example-app
  base:
    image: python:3.11-slim
  applications:
    application:
      packages:
        python:
          requirements: [example-suite]
      executables:
        server:
          source: python
          binary: example-server
  commands:
    serve:
      executable: application.server
      argv: [serve]
  workload:
    command: serve

The base image may already provide Python, or the application may request it through packages.os. Before creating the Python application environment, Reploy verifies the selected interpreter and determines its version. Executables stay with the application that provides them; commands reference them as application.executable.

Add only the nodes the app needs. Common additions are:

• environment.mounts plus docker.mounts for persistent runtime data;
• environment.allow_concurrent for app-command and shell overlap policy;
• environment.install for target, system account, and success output;
• environment.workload.endpoints and docker.workload.endpoints for published services and readiness checks.

Portable Tool Requests

Put application-owned runtime tools in packages.tools. Tool versions and definition revisions are independent of the base distribution:

packages:
  tools:
    - tool:bash==5.2.37~1

This Bash request is qualified on Debian 13 for both linux/amd64 and linux/arm64. A complete staging example is examples/portable-tools/portable-tools.blueprint.yaml in the repository. After staging and building it, reploy shell opens the environment with the selected Bash available.

Bindings and selections use a structured request. For an AMD64 application on Debian 12 or Ubuntu 25.10/26.04, the qualified Playwright request is:

packages:
  tools:
    - tool: playwright
      version: "1.61.0"
      definition_revision: 1
      binding: python
      select:
        browser: chromium

The application needs an available compatible Python interpreter for its Python packages. The browser payload and native dependencies are materialized by Reploy; no upstream browser installer runs. See the exact tuples in Support before selecting a base image or architecture.

Local Development Overrides

Local development choices do not belong in a published blueprint. Stage the blueprint, then open the override editor:

reploy stage ./example.blueprint.yaml
reploy overrides

Use --dir DIR only to select a staging directory explicitly:

reploy overrides --dir ./reploy-staging

The editor loads or creates overrides.yaml beside that staged deployment. The base image can remain From blueprint or use an exact image name such as ubuntu:24.04. Exact names are resolved and locked during validation or build.

Package overrides can select an exact upstream version or a local project. The project browser starts in the directory where the editor was launched. The workspace root is unset by default, so selected paths remain absolute. Set an optional workspace root inside the editor to store paths beneath it using {{ workspace_root }}; paths outside it remain absolute. The root may be an absolute path or a home-relative path such as ~/src. Reploy retains the spelling in the sidecar and expands ~ when it uses the override:

environment:
  id: example
  base:
    image: python:3.13-slim
  vars:
    workspace_root: ~/src
  package_overrides:
    python:
      omegaconf:
        path: "{{ workspace_root }}/OmegaConf"
      hydra-core:
        path: "{{ workspace_root }}/hydra"

An override is used only if the blueprint or a dependency actually requires that package. Installation consumes the artifacts built during staging and does not retain the sidecar or external source paths.

Build-only tools belong to the selected local project. For example, its root .reploy.yaml can declare:

schema: 1
project: omegaconf
type: python
build: setuptools-legacy
requires:
  - tool:java==21~1

Java is then resolved for the isolated source-builder scope and stays out of the application's runtime tool set. This example requires Debian 12/13 or Ubuntu 25.10/26.04 on AMD64. The build type must match the project's metadata: use pep517 when it declares a [build-system] table. Published packages do not activate local recipes, and a recipe cannot supply arbitrary build commands.

The editor shades explicit package dependencies and lists them before override-only mappings. It discovers direct dependencies from static Python project metadata and from a successful trial build. You may add an override-only row for another transitive package, but that row is used only when dependency resolution requires the package. Use the blueprint or reploy bundle add-package when you intend to add a direct requirement.

Press V to save the choices and validate them with the normal build pipeline. Success verifies that versions exist, constraints are compatible, local sources build, and the final environment passes validation. Reploy keeps the trial result for the next reploy build without replacing the current staged image. The editor shows progress and a scrollable log; after a failure, press S to save the log to a new file. Exiting unvalidated choices offers to validate and exit, save without validation, or return to editing.

Validate and Publish

Check syntax and semantics without staging, resolving packages, or building an image:

reploy validate ./example.blueprint.yaml

For local end-to-end development:

reploy stage ./example.blueprint.yaml
reploy build
reploy up
reploy test

Publish the blueprint in a package or Git repository and give users its indexed shorthand or explicit provider ref:

reploy install example-app --scope user
reploy install pypi://example-app/example_app/reploy/example.blueprint.yaml --scope user

For a complete working example, see examples/omegaconf-inspector/reploy/omegaconf-inspector.blueprint.yaml in the Reploy repository.