config.yml Reference

The config.yml file defines the Docker Compose configuration for your test environment, including mock services and environment variables.

Overview

Located at .httptests/config.yml, this file configures:

• Mock HTTP service network aliases
• Additional ports for the mock service
• Environment variables for your Nginx container
• Port configurations

Basic Structure

mock:
  network_aliases:
    - backend
    - api
  additional_ports:
    - 5001
    - 8080
  http_port: 80      # optional
  https_port: 443    # optional

nginx:
  environment:
    API_VERSION: v1
    DEBUG: "true"

Mock Service Configuration

The mock service uses mendhak/http-https-echo, which echoes back request details - perfect for testing proxy behavior.

mock.network_aliases

Type: array (required)
Description: Network hostnames that the mock service responds to within the Docker network.

mock:
  network_aliases:
    - backend
    - api-backend
    - payment-service

Usage: Your nginx configuration's proxy_pass directives should use these aliases:

location /api/ {
    proxy_pass http://backend:80/;      # Uses 'backend' alias
}

location /payment/ {
    proxy_pass http://payment-service:80/;  # Uses 'payment-service' alias
}

Key points:

• Required field - must have at least one alias
• Aliases must be valid DNS names (lowercase, hyphens allowed)
• All aliases point to the same mock service
• Useful for simulating multiple backend services

mock.additional_ports

Type: array (optional)
Description: Additional ports (beyond 80 and 443) to expose on the mock service.

mock:
  additional_ports:
    - 5001
    - 8080
    - 9000
  network_aliases:
    - backend

How it works:

• The mock service always listens on ports 80 (HTTP) and 443 (HTTPS)
• Additional ports are created using socat forwarders
• Each forwarder inherits all network aliases
• Traffic is forwarded from the additional port to the mock's port 80

When to use:

• Your nginx config proxies to non-standard ports
• Testing port-specific routing
• Simulating different services on different ports

Example nginx configuration:

location /api/ {
    proxy_pass http://backend:5001/;    # Requires 5001 in additional_ports
}

location /admin/ {
    proxy_pass http://backend:8080/;    # Requires 8080 in additional_ports
}

mock.http_port

Type: integer (optional)
Default: 80
Description: Primary HTTP port for the mock service.

mock:
  http_port: 8080
  network_aliases:
    - backend

Note: Only override if you need to change the primary HTTP port. Port 80 is always available by default.

mock.https_port

Type: integer (optional)
Default: 443
Description: Primary HTTPS port for the mock service.

mock:
  https_port: 8443
  network_aliases:
    - backend

Note: Only override if you need to change the primary HTTPS port. Port 443 is always available by default.

Legacy: mock.port

Type: integer (deprecated)
Description: Legacy field that maps to http_port.

# Old style (still supported)
mock:
  port: 80

# New style (preferred)
mock:
  http_port: 80

Nginx Service Configuration

nginx.environment

Type: object or array (optional)
Description: Environment variables passed to the Nginx container.

Object Format (Recommended)

nginx:
  environment:
    API_VERSION: v1
    API_HOST: backend
    API_PORT: "80"
    DEBUG: "true"
    MAX_RETRIES: "3"

Array Format

nginx:
  environment:
    - API_VERSION=v1
    - API_HOST=backend
    - API_PORT=80
    - DEBUG=true

Usage in nginx.conf:

# Access environment variables in nginx
location /api/ {
    proxy_pass http://${API_HOST}:${API_PORT}/;
    proxy_set_header X-API-Version $API_VERSION;
}

Key points:

• Values should be strings (quote numbers: "80" not 80)
• Environment variables are available during nginx configuration parsing
• Use ${VAR} syntax in nginx.conf to reference variables
• Common use cases: API endpoints, feature flags, debug settings

Complete Examples

Simple API Proxy

mock:
  network_aliases:
    - backend

Minimal configuration for a simple proxy.

Multi-Service Setup

mock:
  additional_ports:
    - 5001
    - 5002
    - 8080
  network_aliases:
    - auth-service
    - user-service
    - payment-service
    - api-backend

nginx:
  environment:
    AUTH_SERVICE_URL: http://auth-service:5001
    USER_SERVICE_URL: http://user-service:5002
    PAYMENT_SERVICE_URL: http://payment-service:8080
    API_TIMEOUT: "30s"

Simulates multiple microservices on different ports.

Production-like Configuration

mock:
  additional_ports:
    - 5001
  network_aliases:
    - prod-api
    - prod-backend
    - prod-cache

nginx:
  environment:
    ENVIRONMENT: production
    API_VERSION: v2
    BACKEND_HOST: prod-backend
    BACKEND_PORT: "5001"
    CACHE_HOST: prod-cache
    ENABLE_CORS: "true"
    RATE_LIMIT: "100"

Mirrors production environment settings.

Load Balancer Simulation

mock:
  additional_ports:
    - 8081
    - 8082
    - 8083
  network_aliases:
    - backend-1
    - backend-2
    - backend-3
    - backend

nginx:
  environment:
    BACKEND_SERVERS: backend-1:8081,backend-2:8082,backend-3:8083

Tests load balancing across multiple backends.

Generated Docker Compose

HTTPTests automatically generates a docker-compose.yml from your config.yml. Here's what it creates:

Input: config.yml

mock:
  additional_ports:
    - 5001
  network_aliases:
    - backend
    - api

nginx:
  environment:
    API_VERSION: v1

Output: docker-compose.yml

version: "3.9"

services:
  mock:
    container_name: httptests_mock
    image: mendhak/http-https-echo:18
    environment:
      - HTTP_PORT=80
      - HTTPS_PORT=443
    networks:
      default:
        aliases:
          - backend
          - api
  
  mock-forwarder-5001:
    container_name: httptests_forwarder_5001
    image: alpine/socat:latest
    command: "TCP-LISTEN:5001,fork,reuseaddr TCP:mock:80"
    networks:
      default:
        aliases:
          - backend
          - api
    depends_on:
      - mock
  
  nginx:
    container_name: httptests_nginx
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "80:80"
    networks:
      - default
    depends_on:
      - mock
      - mock-forwarder-5001
    environment:
      - API_VERSION=v1

Validation

HTTPTests validates your config.yml:

Required Fields

✅ Must have:

• mock.network_aliases (at least one alias)

Optional Fields

All other fields are optional with sensible defaults.

Common Mistakes

❌ Empty network aliases:

mock:
  network_aliases: []    # ERROR: At least one required

❌ Invalid port numbers:

mock:
  additional_ports:
    - 99999    # ERROR: Port out of range

❌ Invalid YAML syntax:

mock:
network_aliases:    # ERROR: Indentation wrong
  - backend

✅ Correct:

mock:
  network_aliases:
    - backend

Best Practices

1. Use Descriptive Aliases

# Good - Clear purpose
mock:
  network_aliases:
    - user-api
    - auth-service
    - payment-gateway

# Bad - Unclear
mock:
  network_aliases:
    - service1
    - backend2

2. Match Production Topology

# Mirror your production setup
mock:
  additional_ports:
    - 5001    # Auth service port in prod
    - 5002    # User service port in prod
  network_aliases:
    - auth.internal
    - users.internal

3. Use Environment Variables for Dynamic Config

nginx:
  environment:
    API_HOST: ${API_HOST:-backend}      # Default to 'backend'
    API_PORT: ${API_PORT:-80}           # Default to 80
    DEBUG: ${DEBUG:-false}

4. Document Your Configuration

# API Gateway configuration for HTTPTests
# Simulates production microservices architecture
mock:
  # Ports match production service ports
  additional_ports:
    - 5001  # Auth service
    - 5002  # User service
  
  # Aliases match production DNS names
  network_aliases:
    - auth.prod.internal
    - users.prod.internal

nginx:
  # Production environment variables
  environment:
    ENV: test
    API_VERSION: v2

Next Steps

• Learn about test.json configuration
• See examples with real configurations
• Understand upstream tracking