docs: fix container Quick Start to use writable output volumes (#168)

jeremyeder · claude · web-flow · commit 2c6d56548083 · 2025-12-05T12:33:11.000-05:00
Users were unable to access reports because examples used ephemeral container /tmp directory. Updated all examples to show proper pattern: - Mount writable host directory for output - Use mounted path for --output-dir - Reports now accessible on host filesystem Changes: - CONTAINER.md: Updated Quick Start, Usage, CI/CD examples - README.md: Updated Container (Recommended) section - Added troubleshooting section for ephemeral filesystem issue - Removed confusing "Save Output Files" section (integrated into examples) Fixes issue where `podman run --rm -v /repo:/repo:ro agentready assess /repo --output-dir /tmp` writes reports inside container's ephemeral /tmp, destroyed on exit. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -86,3 +86,76 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           attestations: true  # Enable attestations for production
+
+    outputs:
+      new_release: ${{ steps.check_release.outputs.new_release }}
+      version: ${{ steps.check_release.outputs.version }}
+
+  build-container:
+    name: Build and Push Container
+    runs-on: ubuntu-latest
+    needs: release
+    if: needs.release.outputs.new_release == 'true'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/ambient-code/agentready
+          tags: |
+            type=semver,pattern={{version}},value=${{ needs.release.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ needs.release.outputs.version }}
+            type=semver,pattern={{major}},value=${{ needs.release.outputs.version }}
+            type=raw,value=latest
+
+      - name: Build and push container
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Containerfile.scratch
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+      - name: Container summary
+        env:
+          VERSION: ${{ needs.release.outputs.version }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          echo "## Container Published to GHCR" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "📦 **Version**: $VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "🐳 **Registry**: ghcr.io/$REPOSITORY" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Usage" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "# Pull latest" >> $GITHUB_STEP_SUMMARY
+          echo "podman pull ghcr.io/$REPOSITORY:latest" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Pull specific version" >> $GITHUB_STEP_SUMMARY
+          echo "podman pull ghcr.io/$REPOSITORY:$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Run assessment" >> $GITHUB_STEP_SUMMARY
+          echo "podman run --rm -v /path/to/repo:/repo:ro ghcr.io/$REPOSITORY:latest assess /repo --output-dir /tmp/out" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
diff --git a/CONTAINER.md b/CONTAINER.md
@@ -0,0 +1,213 @@
+# AgentReady Container
+
+Size-optimized container (683 MB) for headless environments and CI/CD.
+
+## Quick Start
+
+```bash
+# Pull latest
+podman pull ghcr.io/ambient-code/agentready:latest
+
+# Create output directory
+mkdir -p ~/agentready-reports
+
+# Assess repository
+podman run --rm \
+  -v /path/to/repo:/repo:ro \
+  -v ~/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+
+# Open reports
+open ~/agentready-reports/report-latest.html
+```
+
+## Usage
+
+### Assess AgentReady Itself
+
+```bash
+# Clone AgentReady
+git clone https://github.com/ambient-code/agentready /tmp/agentready
+
+# Create output directory
+mkdir -p ~/agentready-reports
+
+# Run assessment
+podman run --rm \
+  -v /tmp/agentready:/repo:ro \
+  -v ~/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+
+# Open reports
+open ~/agentready-reports/report-latest.html
+```
+
+### Assess Your Repository
+
+```bash
+# Create output directory
+mkdir -p ./agentready-reports
+
+# Local repository
+podman run --rm \
+  -v $(pwd):/repo:ro \
+  -v $(pwd)/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+
+# With additional options
+podman run --rm \
+  -v $(pwd):/repo:ro \
+  -v $(pwd)/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports --verbose
+
+# Exclude specific assessors
+podman run --rm \
+  -v $(pwd):/repo:ro \
+  -v $(pwd)/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports -e type_annotations -e test_coverage
+```
+
+### Save Output Files
+
+```bash
+# Mount writable output directory
+podman run --rm \
+  -v /path/to/repo:/repo:ro \
+  -v $(pwd)/reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+
+# Reports saved: report-*.html, report-*.md, assessment-*.json
+```
+
+## Available Tags
+
+- `latest` - Latest stable release
+- `2.13.0` - Specific version
+- `2.13` - Major.minor version
+- `2` - Major version
+
+```bash
+# Pin to specific version
+podman pull ghcr.io/ambient-code/agentready:2.13.0
+```
+
+## Multi-Architecture Support
+
+Supports both amd64 and arm64:
+
+```bash
+# Automatically pulls correct architecture
+podman pull ghcr.io/ambient-code/agentready:latest
+```
+
+## Docker Compatibility
+
+Replace `podman` with `docker`:
+
+```bash
+docker pull ghcr.io/ambient-code/agentready:latest
+docker run --rm \
+  -v $(pwd):/repo:ro \
+  -v $(pwd)/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Run AgentReady Assessment
+  run: |
+    mkdir -p reports
+    docker pull ghcr.io/ambient-code/agentready:latest
+    docker run --rm \
+      -v ${{ github.workspace }}:/repo:ro \
+      -v ${{ github.workspace }}/reports:/reports \
+      ghcr.io/ambient-code/agentready:latest \
+      assess /repo --output-dir /reports
+
+- name: Upload reports
+  uses: actions/upload-artifact@v4
+  with:
+    name: agentready-reports
+    path: reports/
+```
+
+### GitLab CI
+
+```yaml
+agentready:
+  image: ghcr.io/ambient-code/agentready:latest
+  script:
+    - mkdir -p reports
+    - agentready assess . --output-dir reports
+  artifacts:
+    paths:
+      - reports/
+```
+
+## Building Locally
+
+```bash
+# Clone repository
+git clone https://github.com/ambient-code/agentready
+cd agentready
+
+# Build container
+podman build -t agentready:local -f Containerfile.scratch .
+
+# Test
+podman run --rm agentready:local --version
+```
+
+## Technical Details
+
+- **Base**: python:3.12-slim
+- **Size**: 683 MB
+- **User**: UID 1001 (non-root)
+- **Source**: PyPI (always latest agentready release)
+- **Output**: stdout/stderr (no volume mounts required)
+
+## Troubleshooting
+
+### Reports not accessible on host
+
+Mount a writable output directory to save reports to your host filesystem:
+
+```bash
+mkdir -p ~/agentready-reports
+podman run --rm \
+  -v /repo:/repo:ro \
+  -v ~/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+```
+
+Without the `-v ~/agentready-reports:/reports` mount, reports written to `/tmp` inside the container are destroyed when the container exits.
+
+### Permission denied on mounted volumes
+
+Add SELinux context (`:Z` flag) on SELinux systems:
+
+```bash
+podman run --rm \
+  -v $(pwd):/repo:ro,Z \
+  -v $(pwd)/agentready-reports:/reports,Z \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+```
+
+## Links
+
+- **Container Registry**: https://github.com/ambient-code/agentready/pkgs/container/agentready
+- **Source Code**: https://github.com/ambient-code/agentready
+- **PyPI Package**: https://pypi.org/project/agentready/
+- **Documentation**: https://ambient-code.github.io/agentready/
diff --git a/Containerfile.scratch b/Containerfile.scratch
@@ -0,0 +1,31 @@
+# AgentReady - Size-Optimized Container
+# Self-contained, PyPI-based, stdout output
+#
+# Build: podman build -t agentready -f Containerfile.scratch .
+# Run:   podman run --rm -v /path/to/repo:/repo:ro agentready assess /repo
+
+FROM python:3.12-slim
+
+LABEL name="agentready" \
+      version="2.13.0" \
+      description="Size-optimized AgentReady for headless environments" \
+      maintainer="Jeremy Eder <jeder@redhat.com>"
+
+# Install git (required by AgentReady's GitPython dependency)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install agentready from PyPI (latest stable release)
+RUN pip install --no-cache-dir agentready
+
+# Create non-root user for security
+RUN useradd -u 1001 agentready
+
+# Switch to non-root user
+USER 1001
+WORKDIR /tmp
+
+# Direct agentready CLI execution
+ENTRYPOINT ["agentready"]
+CMD ["--help"]
diff --git a/README.md b/README.md
@@ -19,35 +19,45 @@ AgentReady evaluates your repository across multiple dimensions of code quality,
 
 ## Quick Start
 
-### Bootstrap (Recommended)
-
-Transform your repository with one command:
+### Container (Recommended)
 
 ```bash
-cd /path/to/your/repo
-agentready bootstrap .
-git add . && git commit -m "build: Bootstrap agent-ready infrastructure"
-git push
+# Pull container
+podman pull ghcr.io/ambient-code/agentready:latest
+
+# Create output directory
+mkdir -p ~/agentready-reports
+
+# Assess AgentReady itself
+git clone https://github.com/ambient-code/agentready /tmp/agentready
+podman run --rm \
+  -v /tmp/agentready:/repo:ro \
+  -v ~/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+
+# Assess your repository
+podman run --rm \
+  -v /path/to/your/repo:/repo:ro \
+  -v ~/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+
+# Open reports
+open ~/agentready-reports/report-latest.html
 ```
 
-**What you get:**
-
-- ✅ GitHub Actions workflows (tests, security, AgentReady assessment)
-- ✅ Pre-commit hooks (formatters, linters)
-- ✅ Issue/PR templates
-- ✅ Dependabot configuration
-- ✅ Automated assessment on every PR
-
-**Duration**: <60 seconds
+[See full container documentation →](CONTAINER.md)
 
-[See detailed Bootstrap tutorial →](docs/user-guide.md#bootstrap-your-repository)
-
-### Installation
+### Python Package
 
 ```bash
-# Clone the repository
-git clone https://github.com/yourusername/agentready.git
-cd agentready
+# Install
+pip install agentready
+
+# Assess AgentReady itself
+git clone https://github.com/ambient-code/agentready /tmp/agentready
+agentready assess /tmp/agentready
 
 # Create virtual environment
 python3 -m venv .venv
