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 \
  -e CODEWARD_MODE=main \
  ghcr.io/codeward-io/scan:v0.4.0

Results go to stdout with default policies.

Always set CODEWARD_MODE

The /main mount point is only used when CODEWARD_MODE is set. With it unset the scanner falls back to its local profile and scans the working directory — which inside the image is /, not your repository. Set CODEWARD_MODE=main (or diff), or point global.main_path at the mount in your config.

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:/tmp/.cache:rw \
  -e CODEWARD_MODE=main \
  ghcr.io/codeward-io/scan:v0.4.0

The first run downloads signed Intel snapshot segments for the ecosystems it finds — roughly 87 MB compressed for an npm project, less for most others. Subsequent runs reuse the cache and fetch only what changed, so mounting the cache directory matters more than it used to. See Intel for per-ecosystem sizes; npm expands to about 1.5 GB on disk, so size the volume accordingly.

Air-Gapped / Offline

Use --intel-mode local against a pre-seeded snapshot cache. See Air-Gapped & Offline for how to populate it.

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:/tmp/.cache:rw \
  -e CODEWARD_MODE=diff \
  ghcr.io/codeward-io/scan:v0.4.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:/tmp/.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.4.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
/tmp/.cache	Intel snapshot segments and license cache	Strongly recommended — a cold cache re-downloads segments every run

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	/tmp/.cache	Cache directory path
CODEWARD_INTEL_MODE	auto	api, download, local or disabled
CODEWARD_INTEL_TOKEN	—	Intel API key; switches the default mode to api
CODEWARD_INTEL_REQUIRED	true	Fail the scan if no vulnerability data was obtained
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.4.0	Production (pinned)

Always pin versions in CI for reproducibility:

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

Troubleshooting

Symptom	Fix
Permission denied writing results	chmod 777 results/ or adjust ownership
Cache not reused	Mount a persistent host directory to /tmp/.cache
Scans the wrong tree / finds nothing	CODEWARD_MODE is unset, so /main is ignored — set it
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.