foxhunt/foxhunt-deploy/QUICK_START_BUILD.md

Quick Start: Docker Build Command

Prerequisites

1. Docker installed and running

   docker --version
   docker info  # Verify daemon is running
   

2. foxhunt-deploy configured

   foxhunt-deploy init
   # Edit ~/.runpod/config.toml
   

3. Docker login (for pushing)

   docker login
   

Basic Usage

Build and Push (Default)

foxhunt-deploy build

• Builds: jgrusewski/foxhunt:latest (from config)
• Pushes to Docker Hub
• Uses: Dockerfile.foxhunt-build

Build Only (No Push)

foxhunt-deploy build --no-push

• Builds locally
• Skips registry push
• Useful for testing

Custom Tag

foxhunt-deploy build --tag v1.0.0

• Builds: jgrusewski/foxhunt:v1.0.0
• Pushes to Docker Hub

No Cache Build

foxhunt-deploy build --no-cache

• Rebuilds all layers
• Ignores Docker cache
• Useful after dependency changes

Custom Dockerfile

foxhunt-deploy build --dockerfile Dockerfile.custom

• Uses different Dockerfile
• Keeps same build context

Custom Build Context

foxhunt-deploy build --context ../parent-dir

• Uses different directory as context
• Useful for monorepos

Common Scenarios

Development Build

# Quick local test without pushing
foxhunt-deploy build --tag dev --no-push

Production Build

# Clean build with version tag
foxhunt-deploy build --tag v1.2.3 --no-cache

Test Build

# Build from different Dockerfile without pushing
foxhunt-deploy build --dockerfile Dockerfile.test --tag test --no-push

Multi-Platform Build (Future)

# Not yet implemented, but architecture supports it
# foxhunt-deploy build --platform linux/amd64,linux/arm64

Configuration

Edit ~/.runpod/config.toml:

[docker]
registry = "jgrusewski"      # Your Docker Hub username
image_name = "foxhunt"       # Image name
tag = "latest"               # Default tag

Result: Full tag = jgrusewski/foxhunt:latest

Override tag with: --tag your-tag

Troubleshooting

Docker Not Found

✗ Error: Docker is not installed. Please install Docker Desktop or Docker Engine.

Fix: Install Docker from https://docker.com

Docker Daemon Not Running

✗ Error: Docker daemon is not running. Please start Docker Desktop or Docker service.

Fix: Start Docker Desktop or sudo systemctl start docker

Dockerfile Not Found

✗ Error: Dockerfile not found: Dockerfile.foxhunt-build

Fix: Create Dockerfile or use --dockerfile with correct path

Authentication Failed

✗ Error: Docker registry authentication failed. Please run 'docker login' first.

Fix: Run docker login and enter credentials

Permission Denied

✗ Error: permission denied while trying to connect to Docker daemon

Fix: Add user to docker group: sudo usermod -aG docker $USER

Environment Variables

Override config with environment variables:

export DOCKER_REGISTRY=myregistry.io
export DOCKER_IMAGE_NAME=my-app
foxhunt-deploy build --tag v1.0.0

Output Examples

Successful Build

[1/3] Verifying Docker installation...
ℹ Building Docker image: jgrusewski/foxhunt:latest
ℹ Dockerfile: Dockerfile.foxhunt-build
ℹ Context: .
[2/3] Building Docker image...
⠋ Step 5/12: RUN cargo build --release
✓ Built image: jgrusewski/foxhunt:latest (sha256:abc123...)
[3/3] Pushing to Docker registry...
⠸ Pushing to registry...
✓ Successfully pushed: jgrusewski/foxhunt:latest
✓ Docker build completed successfully!
ℹ Image: jgrusewski/foxhunt:latest

Build Failed

[1/3] Verifying Docker installation...
[2/3] Building Docker image...
✗ Error: Docker build failed with exit code 1:
ERROR [5/12] RUN cargo build --release
error: package `serde v1.0.228` cannot be built because it requires...

No Push

[1/3] Verifying Docker installation...
[2/3] Building Docker image...
✓ Built image: jgrusewski/foxhunt:dev (sha256:xyz789...)
ℹ Skipping push (--no-push flag set)
✓ Docker build completed successfully!
ℹ Image: jgrusewski/foxhunt:dev

Advanced Usage

Verbose Logging

foxhunt-deploy build --verbose

• Shows debug logs
• Useful for troubleshooting

Custom Config File

foxhunt-deploy build --config ./my-config.toml

• Uses different config file
• Useful for multiple environments

Combined Options

foxhunt-deploy build \
  --tag v1.0.0-rc1 \
  --dockerfile Dockerfile.prod \
  --no-cache \
  --verbose

Integration with CI/CD

GitHub Actions

- name: Build Docker Image
  run: |
    foxhunt-deploy build --tag ${{ github.sha }}

GitLab CI

build:
  script:
    - foxhunt-deploy build --tag ${CI_COMMIT_SHA}

Jenkins

stage('Build') {
  steps {
    sh 'foxhunt-deploy build --tag ${GIT_COMMIT}'
  }
}

Performance Tips

1. Use BuildKit (Docker 18.09+)

   export DOCKER_BUILDKIT=1
   foxhunt-deploy build
   

2. Leverage Layer Caching

   • Don't use --no-cache unless necessary
   • Order Dockerfile for optimal caching
   • Copy dependency files before source code

3. Multi-Stage Builds

   • Use Dockerfile.foxhunt-build pattern
   • Separate build and runtime stages
   • Keep final image small

4. Parallel Builds

   • Build multiple tags in parallel (manual)

   foxhunt-deploy build --tag v1.0.0 &
   foxhunt-deploy build --tag latest &
   wait
   

Next Steps

After building, you can:

1. Deploy to RunPod

   foxhunt-deploy deploy --gpu "RTX A4000"
   

2. Run locally

   docker run -it jgrusewski/foxhunt:latest bash
   

3. Inspect image

   docker images jgrusewski/foxhunt
   docker history jgrusewski/foxhunt:latest
   

4. Test image

   docker run --rm jgrusewski/foxhunt:latest --version
   

Help

foxhunt-deploy build --help
foxhunt-deploy --help

Support

• 📖 Documentation: DOCKER_BUILD_MILESTONE2.md
• 📋 Summary: IMPLEMENTATION_SUMMARY.md
• 🐛 Issues: Check stderr output with --verbose
• 💬 Questions: Review help text and config file