Docker Setup - HTTP File Runner

Overview

This project automatically publishes Docker containers to both GitHub Container Registry (GHCR) and DockerHub when a new release is created. The containers provide a portable way to run HTTP File Runner without installing dependencies.

Supported Platforms

Linux AMD64: Standard x86_64 architecture
Linux ARM64: ARM-based systems (Apple M1/M2, AWS Graviton)
Multi-arch images: Automatic platform detection

Container Registries

The project publishes to two major container registries for maximum accessibility.

GitHub Container Registry (GHCR)

                        # Pull from GitHub Container Registry
docker pull ghcr.io/christianhelle/httprunner:latest

# Run with GitHub Container Registry image
docker run --rm -v ${PWD}:/app ghcr.io/christianhelle/httprunner:latest *.http
                    

DockerHub

                        # Pull from DockerHub
docker pull christianhelle/httprunner:latest

# Run with DockerHub image
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest *.http
                    

Registry Features

GHCR: Integrated with GitHub, supports private repos, excellent for CI/CD
DockerHub: Most popular registry, great for public distribution
Both: Support multi-architecture images and vulnerability scanning

Required Secrets

The following repository secrets must be configured for automated publishing.

GitHub Secrets Configuration

GITHUB_TOKEN

Auto-provided

Automatically provided by GitHub Actions for GHCR authentication

DOCKERHUB_USERNAME

string

DockerHub username for authentication

DOCKERHUB_TOKEN

string

DockerHub access token (not password) for secure authentication

Setting Up DockerHub Token

Log in to DockerHub
Go to Account Settings → Security
Create new access token with read/write permissions
Add token to GitHub repository secrets

Container Tags

Images are tagged automatically based on the release version and additional metadata.

Tagging Strategy

latest

Always points to the most recent stable release

v1.2.3

Specific version tag for reproducible deployments

v1.2

Minor version tag for compatible updates

v1

Major version tag for stability

Image Metadata

All images include comprehensive metadata for better discoverability and maintenance:

Source repository and commit SHA
Build timestamp and version
License and description
Maintainer information

Usage

Multiple ways to use HTTP File Runner containers for different scenarios.

Basic Usage

                        # Run single HTTP file
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest requests.http

# Run with verbose output
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest --verbose requests.http

# Discover and run all HTTP files
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest --discover
                    

Advanced Usage

                        # Use specific environment
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest --env production api-tests.http

# Save logs to file
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest --log test-results.log --discover

# Custom working directory
docker run --rm -v ${PWD}/tests:/app christianhelle/httprunner:latest *.http
                    

CI/CD Integration

                        # GitHub Actions example
- name: Run HTTP tests
  run: |
    docker run --rm -v ${{ github.workspace }}:/app \
      ghcr.io/christianhelle/httprunner:latest \
      --discover --log results.log

# Docker Compose example
version: '3.8'
services:
  api-tests:
    image: christianhelle/httprunner:latest
    volumes:
      - ./tests:/app
    command: ["--discover", "--verbose"]
                    

Docker Networking

When running httprunner in a Docker container, understanding networking is crucial for accessing services on your host machine.

The Localhost Problem

Important: localhost inside a Docker container refers to the container itself, not your host machine. Requests to http://localhost:8080 will fail with connection refused errors.

Solutions by Platform

macOS and Windows (Docker Desktop)

Use the special hostname host.docker.internal to access host services:

                        # In your .http file
GET http://host.docker.internal:8080/api/users

# Run with Docker
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest test.http
                    

Linux - Option 1: Host Networking (Simplest)

Use --network=host to share the host's network stack:

                        # In your .http file - use localhost normally
GET http://localhost:8080/api/users

# Run with host networking
docker run --rm --network=host \
  -v ${PWD}:/app christianhelle/httprunner:latest test.http
                    

Linux - Option 2: Host Gateway (Docker 20.10+)

Add host.docker.internal using the host gateway:

                        # In your .http file
GET http://host.docker.internal:8080/api/users

# Run with host gateway
docker run --rm --add-host=host.docker.internal:host-gateway \
  -v ${PWD}:/app christianhelle/httprunner:latest test.http
                    

Linux - Option 3: Direct IP Address

Use your host's actual IP address (e.g., 192.168.1.100):

                        # Find your IP
hostname -I | awk '{print $1}'

# In your .http file
GET http://192.168.1.100:8080/api/users
                    

Cross-Platform Best Practice

Use environment variables for portability across different platforms:

                        # In your .http file
@hostname=localhost

GET http://{{hostname}}:8080/api/users
                    

Create an environment file http-client.env.json:

                        {
  "local": {
    "hostname": "localhost"
  },
  "docker-mac": {
    "hostname": "host.docker.internal"
  },
  "docker-linux": {
    "hostname": "host.docker.internal"
  }
}
                    

Run with the appropriate environment:

                        # On host machine
httprunner test.http --env local

# In Docker on macOS/Windows
docker run --rm -v ${PWD}:/app \
  christianhelle/httprunner:latest test.http --env docker-mac

# In Docker on Linux (with host gateway)
docker run --rm --add-host=host.docker.internal:host-gateway \
  -v ${PWD}:/app christianhelle/httprunner:latest test.http --env docker-linux
                    

Quick Reference

macOS/Windows

Use host.docker.internal

Linux (simplest)

Use --network=host flag

Linux (isolated)

Use --add-host=host.docker.internal:host-gateway

Cross-platform

Use environment variables with different configs

Troubleshooting

Common issues and solutions when using Docker containers.

Connection Refused Errors

If you see connection refused errors when accessing localhost:

Verify your service is running on the host machine
Use host.docker.internal instead of localhost (macOS/Windows)
Use --network=host on Linux
Check firewall settings aren't blocking container access

File Not Found Errors

If your .http files aren't found:

Ensure files are in the mounted directory
Use absolute paths in the container: /app/yourfile.http
Verify the mount point matches: -v ${PWD}:/app

Permission Denied When Writing Logs

To enable log file writing, mount without readonly flag:

                        # Remove readonly to allow log writing
docker run --rm -v ${PWD}:/app \
  christianhelle/httprunner:latest test.http --log results.log
                    

Testing Network Connectivity

Verify Docker networking is working:

                        # Start a test server on your host
python3 -m http.server 8080

# Create a test file
echo "GET http://host.docker.internal:8080/" > test.http

# Test from Docker (macOS/Windows)
docker run --rm -v ${PWD}:/app christianhelle/httprunner:latest test.http

# Test from Docker (Linux)
docker run --rm --network=host -v ${PWD}:/app \
  christianhelle/httprunner:latest test.http
                    

Additional Resources

Workflow Trigger

Container publishing is automated through GitHub Actions workflows.

Trigger Conditions

Release Creation: New GitHub release triggers container build
Tag Push: Version tags (v*.*.*) trigger publishing
Manual Trigger: Workflow can be run manually from Actions tab

Build Process

Checkout source code and setup build environment
Build multi-architecture Docker images
Run security scans on container images
Login to both GHCR and DockerHub registries
Push images with appropriate tags to both registries
Update container registry metadata

Security Scanning

All container images undergo security scanning before publication:

Trivy scanning: Vulnerability detection in base images and dependencies
Best practices: Dockerfile security recommendations
Supply chain: Verification of build reproducibility

Note: Container images are only published for official releases to ensure stability and security.