Docker Installation

Run Codeward via Docker for consistent scanning across any CI system or local development.

Quick Start

Scan a repository with defaults:

docker run --rm \
  -v /path/to/your/repo:/main:rw \
  ghcr.io/codeward-io/scan:v0.3.0

Results go to stdout with default policies.

With Cache (Recommended)

Persistent cache avoids re-downloading the vulnerability database on every run:

mkdir -p cache
docker run --rm \
  -v /path/to/your/repo:/main:rw \
  -v $(pwd)/cache:/.cache:rw \
  ghcr.io/codeward-io/scan:v0.3.0

First run downloads the Trivy DB (~30s). Subsequent runs reuse it (~5s).

Air-Gapped / Offline

Set TRIVY_SKIP_DB_UPDATE=true to skip database downloads entirely. Useful for air-gapped environments with a pre-populated cache.

PR Diff Scan

Compare a feature branch against main:

docker run --rm \
  -v /path/to/main-branch:/main:rw \
  -v /path/to/feature-branch:/branch:rw \
  -v $(pwd)/cache:/.cache:rw \
  -e CODEWARD_MODE=diff \
  ghcr.io/codeward-io/scan:v0.3.0

Results are categorized as new, changed, removed, or existing.

Full Example with GitHub Integration

mkdir -p results cache
docker run --rm \
  -v /path/to/main-branch:/main:rw \
  -v /path/to/feature-branch:/branch:rw \
  -v $(pwd)/cache:/.cache:rw \
  -v $(pwd)/results:/.results:rw \
  -v $(pwd)/.codeward.yaml:/config/.codeward.yaml:ro \
  -e CODEWARD_MODE=diff \
  -e CODEWARD_CONFIG_PATH=/config/.codeward.yaml \
  -e CODEWARD_GITHUB_TOKEN=$GITHUB_TOKEN \
  -e CODEWARD_GITHUB_OWNER=myorg \
  -e CODEWARD_GITHUB_REPOSITORY=myrepo \
  -e CODEWARD_GITHUB_PR_NUMBER=123 \
  ghcr.io/codeward-io/scan:v0.3.0

Volume Mounts

Container Path	Purpose	Required
/main	Main/base branch checkout	Yes
/branch	Feature branch checkout	Only for diff mode
/results	File-based report output	If using file: destinations
/.cache	Trivy DB and scan cache	Recommended

Environment Variables

See CLI & Environment Variables for the complete list. Key variables:

Variable	Default	Description
CODEWARD_MODE	main	diff or main
CODEWARD_CONFIG_PATH	.codeward.json in repo	Config file path (YAML or JSON)
CODEWARD_PRIVATE_CONFIG_PATH	—	Private config (merged with primary)
CODEWARD_CACHE_DIR	/.cache	Cache directory path
TRIVY_SKIP_DB_UPDATE	false	Skip Trivy DB download (air-gapped)
CODEWARD_GITHUB_TOKEN	—	GitHub API token
CODEWARD_GITHUB_OWNER	—	Repository owner
CODEWARD_GITHUB_REPOSITORY	—	Repository name
CODEWARD_GITHUB_PR_NUMBER	—	PR number (diff mode)

Image Versions

Tag	Use Case
latest	Quick experiments
v0.3.0	Production (pinned)

Always pin versions in CI for reproducibility:

ghcr.io/codeward-io/scan:v0.3.0

Troubleshooting

Symptom	Fix
Permission denied writing results	chmod 777 results/ or adjust ownership
Cache not reused	Mount a persistent host directory to /.cache
Everything marked "new"	Mount main branch at /main and set CODEWARD_MODE=diff
No PR comment posted	Set all CODEWARD_GITHUB_* variables

See Troubleshooting for more solutions.