Skip to content

Project Structure

pei-docker-cli create generates a working project skeleton. configure adds the compose file and generated helper scripts.

Root Directory

Path Purpose
user_config.yml The config you edit most often
reference_config.yml Full commented template for lookup
compose-template.yml The base compose template PeiDocker fills in
docker-compose.yml Generated by configure in all documented build modes
stage-1.Dockerfile System-layer build template
stage-2.Dockerfile Final-layer build template for the default two-stage and merged-build workflows; it remains in the scaffold even if your config omits stage_2
PEI-DOCKER-USAGE-GUIDE.md Generated quick guide inside the created project
examples/ Packaged examples copied into the project when --with-examples is enabled
installation/ Files copied into the image under /pei-from-host

installation/

The installation/ tree is the core handoff between your project directory and the generated images.

Path Purpose
installation/stage-1/internals/ Core scripts for env setup, SSH, users, cleanup, and entrypoint behavior
installation/stage-1/system/ Canonical built-in installers such as Pixi, UV, Node.js, ROS2, and OpenCV
installation/stage-1/custom/ Your stage-1 shell scripts
installation/stage-1/generated/ Wrapper scripts produced by configure
installation/stage-2/internals/ Stage-2 runtime scripts, storage creation, and entrypoint logic
installation/stage-2/system/ Mostly compatibility wrappers that forward to stage-1 canonical installers
installation/stage-2/custom/ Your stage-2 shell scripts
installation/stage-2/generated/ Stage-2 wrapper scripts produced by configure

Generated Files After configure

  • docker-compose.yml
  • installation/stage-1/generated/_custom-on-build.sh
  • installation/stage-1/generated/_custom-on-first-run.sh
  • installation/stage-1/generated/_custom-on-every-run.sh
  • installation/stage-1/generated/_custom-on-user-login.sh
  • installation/stage-1/generated/_custom-on-entry.sh
  • Matching stage-2 generated wrappers
  • installation/stage-1/generated/_etc_environment.sh
  • installation/stage-2/generated/_etc_environment.sh
  • Optional merged artifacts when you run pei-docker-cli configure --with-merged

Mode-Specific Outcomes

  • stage-1-only: docker-compose.yml contains only the stage-1 service, but the scaffold still keeps the stage-2 template files and generated wrapper paths available if you add stage_2 later.
  • two-stage Compose: docker-compose.yml contains both stage-1 and stage-2, and the final runtime workflow usually targets stage-2.
  • merged build: configure --with-merged still writes docker-compose.yml, but it also adds merged.Dockerfile, merged.env, build-merged.sh, and run-merged.sh for a plain docker build / docker run workflow.

Read This Before Editing

  • Edit user_config.yml and your custom scripts, not the generated wrapper files.
  • pei-docker-cli configure overwrites docker-compose.yml and refreshes installation/stage-*/generated/.
  • Mount and storage paths in user_config.yml are relative to how PeiDocker populates /hard/... and /soft/... inside the container, not relative to your host repo.

Next Step

Continue with Build Modes if you still need to choose a workflow, or Two-Stage Architecture if you want to understand why the default model separates stage-1 and stage-2.