Docker

🚀Run Custy with Docker

Release Image or Source Build

Build Custy locally and run its self-contained CLI against a deliberately mounted project workspace.

Commanddocker build --target production -t custy-prod:latest .

📦Category

Getting Started

🚀Quick Command

docker [build|run|compose] [OPTIONS]

---

local imageDocker Composeworkspace mount

---

📦

Base Image

Python 3.14 slim

📌

Included Tools

pip, Git, Make, Micro, Nano, and Vim

📁

Container Workspace

/workspace

🐳

Recommended Source

Exact GHCR release tag or local build

Overview

Custy's multi-stage Dockerfile provides development and production image targets. Both include Python 3.14, pip, Git, Make, and the Micro, Nano, Vim, and Vi terminal editors. The production target installs the runtime package, while the development target installs Custy in editable mode with its development dependencies.

This path removes the need for a host Python or Git installation. Docker must still receive the intended project directory, repository metadata, identity, and credentials required by the selected Custy operation.

ℹ️Pin automated use to an exact release

Published releases are available from GHCR. Use an exact tag such as v2.1.2 for reproducible automation. Moving aliases such as v2.1, v2, and latest are convenient for controlled upgrades, while a local source build is appropriate when validating unpublished changes.

---

Requirements

📌Requirements

Docker Engine

Required

Install and start a Docker environment that can build and run Linux containers.

Custy Source Checkout

Required

Build the image from the repository containing Custy's Dockerfile and package metadata.

Project Workspace

Required

Mount the exact project root, including its .git directory when Git operations are required, at /workspace.

Docker Compose Plugin

Optional

Install Compose only when using the repository's development or production services.

Make

Optional

Use Make as a convenience wrapper around the repository's Docker and Compose commands.

Project Backup

Recommended

Commit or back up important work before exposing a real project to mutating commands.

💡Host Python and Git are not required

The image already contains Python 3.14, pip, Git, Make, Micro, Nano, Vim, and Vi. Host Git remains useful for inspecting the project before and after a run, but the containerized Custy process uses the Git executable inside the image.

---

What the Image Contains

✨Docker Build Targets

📦Shared Base

Python 3.14 slim, pip, Git, Make, Micro, Nano, Vim, Vi, the /workspace working directory, and the Custy source tree.

🏷️Production

A normal runtime package installation with custy as the container entrypoint.

🚀Development

An editable installation with the optional development dependency group and the same interactive terminal editors.

📁Project Mount

The host project mounted at /workspace becomes the real working tree that Custy reads and may modify.

---

Build the Production Image

From the Custy source root, the Make helper is the recommended local build. It derives a normalized package version from Git before .git is excluded from the Docker context, so custy --version inside the image matches the source checkpoint.

Build and verify

bash

make c-build-prod
docker run --rm custy-prod:latest --version
docker run --rm custy-prod:latest --help

For a direct build, pass the intended PEP 440 package version explicitly. The build argument controls Custy's installed package metadata and banner; it does not change the version of a mounted target project.

Direct production build

bash

docker build --build-arg CUSTY_BUILD_VERSION=2.1.2 --target production -t custy-prod:latest .

Use --target development -t custy-dev:latest when testing or developing Custy itself.

---

Pull a Published Production Image

Stable releases publish four coordinated GHCR tags. All version aliases retain Custy's conventional v prefix.

Tag form	Example	Behavior
Exact release	v2.1.2	Immutable release selection and the recommended choice for CI or reproducible use.
Minor alias	v2.1	Moves to the newest stable patch in the 2.1 line.
Major alias	v2	Moves to the newest stable release in the 2 line.
Latest alias	latest	Moves to the newest stable Custy release.

Pull a published Custy image

bash

docker pull ghcr.io/devalltect00/custy:v2.1.2
docker pull ghcr.io/devalltect00/custy:v2.1
docker pull ghcr.io/devalltect00/custy:v2
docker pull ghcr.io/devalltect00/custy:latest

⚠️Prereleases do not move stable aliases

A prerelease such as v2.2.0-rc.1 publishes only its exact tag. It never updates v2.2, v2, or latest, so opt-in testing cannot silently replace a stable image.

---

Run Custy on a Project

Run the following commands from the root of the project that Custy should manage. Because the image uses custy as its entrypoint, arguments after the image name are Custy arguments.

Running the image without a command is also valid: Custy displays its root help and exits successfully.

Windows PowerShell

powershell

docker run --rm -it -v "${PWD}:/workspace" custy-prod:latest --help
docker run --rm -it -v "${PWD}:/workspace" custy-prod:latest init
docker run --rm -it -v "${PWD}:/workspace" custy-prod:latest validate

Linux or macOS

bash

docker run --rm -it -v "$(pwd):/workspace" custy-prod:latest --help
docker run --rm -it -v "$(pwd):/workspace" custy-prod:latest init
docker run --rm -it -v "$(pwd):/workspace" custy-prod:latest validate

ℹ️The mounted project does not need an app directory

Custy detects Python, Node.js, mixed, and generic layouts at command runtime. A Docusaurus, React, PHP, documentation-only, or otherwise generic repository can use the project root when no conventional src/ or app/ directory is available. Run custy init to create project-owned Custy configuration; do not add an empty app/ directory as a workaround.

⚠️Mounted files are real project files

Container isolation does not protect a mounted repository from changes. Custy can edit mounted files, stage changes, and create Git history. Use global dry-run mode for supported consequential operations and review the volume mount before normal execution.

💡Interactive profiles use the configured container editor

The production image includes Micro, Nano, Vim, and Vi for Commit, Tag, Dev, Release, and Full profiles. Micro is the default container candidate. Keep -it in the Docker command so the selected editor receives an interactive terminal. Custy checks VISUAL and EDITOR first when enabled, then uses tool.custy.editor.candidates.container in order. See Editor configuration for supported identifiers, fallback behavior, and container keybindings. Dry-run reports the editor step without launching a process.

⚠️Mounted Git hooks remain project policy

The production image includes cz and pre-commit, but project-specific Git hooks still come from the mounted repository. With the recommended [tool.custy.git.hooks] mode = "auto", projects without hooks use normal Git, compatible hooks run natively, and a recognized Windows-generated pre-commit wrapper can run its configured checks directly inside Linux. Custy continues only after those checks pass; unknown custom hooks are never bypassed. See Git Commit Hooks.

Interactive release profile

powershell

docker run --rm -it -v "${PWD}:/workspace" -w /workspace custy-prod:latest run release

---

Git Identity and Remote Access

Mounting the project makes its local .git directory available, but it does not automatically copy the host user's global Git configuration, SSH keys, or credential-manager session into the container.

• Configure user.name and user.email in the repository or provide an intentionally reviewed Git configuration before commit or tag flows.
• Provide SSH keys, tokens, or another supported Git credential mechanism only when a push is required.
• Keep normal Git and SSH authentication first. For supported GitHub or GitLab HTTPS remotes, Custy can optionally read a token from a protected file mounted at /run/secrets/custy or from a named environment variable.
• Review every credential and configuration mount carefully; never bake secrets into the image.
• Local-only commands such as initialization do not require remote credentials.

🛡️Dry run does not authenticate a future push

A successful preview cannot guarantee that normal execution has valid remote credentials or that the destination remains unchanged. Verify authentication and remote URLs separately before publication.

💡Optional Custy credential fallback

Run custy configure credentials in the target project to configure policy. The recommended container_only = true keeps local credential-manager sessions unchanged. Mount the external credential directory read-only or pass an approved token environment variable to Docker. See Configure Credentials.

Protected token-file mount

powershell

docker run --rm -it -v "${PWD}:/workspace" -v "$env:LOCALAPPDATA/Custy/credentials:/run/secrets/custy:ro" -w /workspace custy-prod:latest push

---

Use Docker Compose

The Compose files are primarily development helpers for the Custy source checkout itself. Their base service mounts the current checkout at /workspace. Use direct docker run -v commands when operating on a separate project root.

Production service

bash

docker compose -f docker-compose.yml -f docker-compose.prod.yml build app
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm app --help
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm app init

Use the development stack for Custy testing and contributor tools.

Development services

bash

docker compose -f docker-compose.yml -f docker-compose.dev.yml build app
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app --help
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm test

---

Optional Makefile Helpers

From the Custy source checkout, GNU Make can wrap the local Docker and Compose commands.

Selected local-image helpers

bash

# Build Dockerfile targets directly
make d-build-prod
make d-init

# Use the Docker Compose services

make c-build-prod

# Create and inspect external credentials

make d-credentials-set-github
make d-credentials-status
make d-credentials-test CUSTY_CREDENTIALS_REMOTE=origin

# Opt in to a read-only credential mount for push

make d-run-push CUSTY_CREDENTIALS_MOUNT=true

CUSTY_CREDENTIALS_MOUNT defaults to false, preserving native Git, SSH, and manual interactive authentication. Setting it to true adds the external credential directory to runtime targets as a read-only volume. Credential set helpers always use a writable mount, while status and test helpers always use read-only access. The same interface is available through c-credentials-* / c-run-push for Compose and r-custy-credentials-* / r-custy-run-push for a published image.

Override CUSTY_CREDENTIALS_HOST_DIR when the files do not live in the platform default directory. The Make interface accepts a directory path, never a token value. See Credential Examples for the complete behavior matrix and platform defaults.

⚠️Remote-image Make targets are not recommended yet

Targets beginning with r-custy- expect a published registry image. Use the local d- or c- helpers until a Custy release explicitly documents a valid remote image and tag.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Python Installation

Install Custy natively from source, release assets, or Git.

Quick Start

Initialize and validate the mounted project.

custy init

Understand generated files and overwrite behavior.

custy run

Review public profiles before containerized execution.