Merge pull request #331 from pipecat-ai/mb/pcc-docker-cli

pcc: Add docker command docs

Author: markbackman

deployment/pipecat-cloud/cli-reference/docker.mdx

@@ -0,0 +1,168 @@
+---
+title: docker
+description: "Build and push Docker images for agent deployments"
+---
+
+The `docker` command provides utilities for building, tagging, and pushing Docker images to container registries. This command automatically parses registry information from your deployment configuration and supports both Docker Hub and custom registries.
+
+## build-push
+
+Build, tag, and push a Docker image for your agent deployment. This command reads configuration from your `pcc-deploy.toml` file to automatically determine registry settings, image names, and versions.
+
+**Usage:**
+
+```shell
+pcc docker build-push [ARGS] [OPTIONS]
+```
+
+**Arguments:**
+
+<ParamField path="agent-name" type="string">
+  Name of the agent to build image for. If not provided, uses the `agent_name`
+  from your `pcc-deploy.toml` file.
+</ParamField>
+
+**Registry Configuration:**
+
+<ParamField path="--registry / -r" type="string">
+  Registry type to push to. Supported values: `dockerhub`, `custom`. When not
+  specified, automatically detected from the `image` field in your
+  `pcc-deploy.toml` file.
+</ParamField>
+
+<ParamField path="--username / -u" type="string">
+  Registry username for authentication. When not specified, automatically parsed
+  from the `image` field in your `pcc-deploy.toml` file (e.g., `myusername` from
+  `myusername/app:1.0`).
+</ParamField>
+
+<ParamField path="--registry-url" type="string">
+  Custom registry URL (required for custom registries). When not specified,
+  automatically parsed from the `image` field for custom registries (e.g.,
+  `gcr.io` from `gcr.io/project/app:1.0`).
+</ParamField>
+
+**Build Configuration:**
+
+<ParamField path="--version / -v" type="string">
+  Version tag for the image. When not specified, automatically extracted from
+  the `image` field in your `pcc-deploy.toml` file (e.g., `1.0` from
+  `myusername/app:1.0`).
+</ParamField>
+
+<ParamField path="--no-push" type="boolean" default="false">
+  Build and tag only, do not push to registry. Useful for local testing or when
+  you want to push manually later.
+</ParamField>
+
+<ParamField path="--no-latest" type="boolean" default="false">
+  Do not tag the image as `latest`. By default, images are tagged with both the
+  specified version and `latest`.
+</ParamField>
+
+## Configuration
+
+The `docker build-push` command reads configuration from your `pcc-deploy.toml` file to minimize required command-line arguments. Here's how different registry setups work:
+
+### Docker Hub (Default)
+
+For Docker Hub repositories, the minimal configuration is:
+
+```toml
+agent_name = "my-agent"
+image = "myusername/my-agent:1.0"
+```
+
+This automatically configures:
+
+- Registry: `dockerhub`
+- Username: `myusername`
+- Agent name: `my-agent`
+- Version: `1.0`
+
+### Custom Registry
+
+For custom registries like Google Container Registry, AWS ECR, or private registries:
+
+```toml
+agent_name = "my-agent"
+image = "gcr.io/my-project/my-agent:1.0"
+```
+
+This automatically configures:
+
+- Registry: `custom`
+- Registry URL: `gcr.io`
+- Username/Project: `my-project`
+- Agent name: `my-agent`
+- Version: `1.0`
+
+### Docker Configuration Section
+
+For advanced configuration, add a `[docker]` section:
+
+```toml
+agent_name = "my-agent"
+image = "myusername/my-agent:1.0"
+
+[docker]
+auto_latest = false  # Don't tag as 'latest'
+```
+
+Available `[docker]` options:
+
+<ParamField path="auto_latest" type="boolean" default="true">
+  Whether to automatically tag the image as `latest` in addition to the
+  specified version.
+</ParamField>
+
+## Examples
+
+### Basic Usage (Recommended)
+
+With a properly configured `pcc-deploy.toml`:
+
+```shell
+# Build and push using all configuration from pcc-deploy.toml
+pcc docker build-push
+```
+
+### Override Version
+
+```shell
+# Use a different version than what's in pcc-deploy.toml
+pcc docker build-push --version 2.0
+```
+
+### Build Only
+
+```shell
+# Build and tag locally without pushing
+pcc docker build-push --no-push
+```
+
+### Different Registry
+
+```shell
+# Override registry settings for one-time builds
+pcc docker build-push --registry custom --registry-url my-registry.com --username myuser
+```
+
+### Skip Latest Tag
+
+```shell
+# Only tag with the specific version, not 'latest'
+pcc docker build-push --no-latest
+```
+
+## Platform Support
+
+All images are built for the `linux/arm64` platform, which is required for Pipecat Cloud deployments. This is automatically configured and cannot be changed.
+
+## Error Handling
+
+The command provides helpful error messages for common issues:
+
+- **Authentication errors**: Suggests the appropriate `docker login` command
+- **Missing Dockerfile**: Indicates that a Dockerfile must be present in the current directory
+- **Registry access issues**: Provides guidance on checking permissions and authentication

docs.json

@@ -547,6 +547,7 @@
                   "deployment/pipecat-cloud/cli-reference/agent",
                   "deployment/pipecat-cloud/cli-reference/auth",
                   "deployment/pipecat-cloud/cli-reference/deploy",
+                  "deployment/pipecat-cloud/cli-reference/docker",
                   "deployment/pipecat-cloud/cli-reference/init",
                   "deployment/pipecat-cloud/cli-reference/organizations",
                   "deployment/pipecat-cloud/cli-reference/secrets"