view release on metacpan or  search on metacpan

docker/README.md  view on Meta::CPAN

# Using BUILD directly
docker/BUILD -e dev                 # Development build
docker/BUILD                        # Production build
docker/BUILD --user myuser --perl 5.40.2 --no-cache --nopush

# Access shell in specific container
docker/BUILD cpancover-shell
docker/BUILD devel-cover-dc-shell
```

### Build Options

- `--user`: Docker Hub username (default: pjcj)
- `--perl`: Perl version to use (default: 5.42.0)
- `--image`: Image name (cpancover or cpancover_dev)
- `--src`: Source branch/path (default: main)
- `--no-cache`: Force rebuild without cache
- `--nopush`: Skip pushing to Docker Hub
- `--env`: Environment (prod/dev)

## Image Versioning

Production builds of `pjcj/cpancover` are tagged with a combined date and git
SHA, for example `2026-02-15-1430-c1213eac`. The `:latest` tag is always
updated alongside the versioned tag, so pulling `:latest` gives you the most
recent build while every previous build remains addressable.

### Tag format

```text
YYYY-MM-DD-HHMM-<short-sha>
```

The timestamp is UTC and the SHA is from `git rev-parse --short HEAD` at build
time.

### Managing tags

List all versioned tags on Docker Hub:

```bash
dc docker-show-tags
```

Prune old versioned tags, keeping the most recent:

```bash
dc docker-prune-tags        # keep the 20 most recent (default)
dc docker-prune-tags 10     # keep the 10 most recent
dc -d docker-prune-tags     # dry run — list what would be deleted
```

The `latest` tag is never deleted. Two environment variables are required:

- `HUB_USERNAME` — your Docker Hub username
- `HUB_TOKEN` — a Personal Access Token (PAT)

These are needed because tag deletion uses the Docker Hub web API, which
authenticates separately from `docker push` (which uses `docker login`
credentials). To create a PAT:

1. Go to <https://hub.docker.com/settings/security>
2. Click **Personal access tokens** and then **Generate new token**
3. Give it **Read, Write & Delete** permissions
4. Copy the token and export it as `HUB_TOKEN`

## Running the System

### Local Development

For local development and testing:

```bash
# Set up environment
cd /path/to/Devel--Cover
. ./utils/setup

# Run coverage for specific modules
echo "Some::Module" | utils/dc cpancover

# Run with local changes
utils/dc --env=dev cpancover-build-module Some::Module
```

### Production Deployment

The production system runs on cpancover.com:

```bash
# Controller manages the overall process
utils/dc cpancover-controller-run

# Or run once for testing
utils/dc cpancover-controller-run-once
```

### Container Orchestration

The system uses two execution models:

#### 1. Direct Execution (Development)

```text
Host → cpancover binary → Docker containers (per module)
```

Commands that run orchestration **directly from the host**:

- `dc cpancover` - Runs cpancover binary on host
- `dc cpancover-build-module` - Builds single module from host
- `dc cpancover-run-once` - Full cycle from host
- `dc cpancover-generate-html` - Generates HTML from host

#### 2. Controller-based Execution (Production)

```text
Host → Controller container → Worker containers (per module)
```

Commands that run orchestration **through a controller container**: