Installation¶

Health Check Configuration
- Health Check Endpoint
- Docker Health Check Configuration

CredProxy can be deployed via Docker (recommended) or from source for development.

Docker Installation (Recommended)¶

Prerequisites¶

Docker 20.10+
Docker Compose v2.0+ (optional, for multi-container setups)
AWS credentials configured (AWS CLI profile or environment variables)

Quick Start¶

# Clone the repository
git clone https://github.com/johnpreston/credproxy.git
cd credproxy

# Build the Docker image
docker build -t credproxy:latest .

# Run with docker compose
docker compose up --build

The service will be available at http://localhost:1338

Docker Image¶

The official Docker image is built on Alpine Linux for minimal size and includes:

Python 3.11+
lprobe for health checks
All required dependencies

Health checks are configured using lprobe, a lightweight HTTP health check tool designed for containers.

See Health Check Configuration for complete health check configuration details.

From Source Installation¶

Prerequisites¶

Python 3.10+
Poetry 1.5+
AWS CLI configured

Installation Steps¶

# Clone the repository
git clone https://github.com/johnpreston/credproxy.git
cd credproxy

# Install dependencies with poetry
poetry install

# Run in development mode
poetry run credproxy --dev --config config.yaml

# Or run in testing mode
poetry run credproxy --config config.yaml

Development Setup¶

For development with hot-reload:

# Install development dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=credproxy

# Format code
poetry run black credproxy tests
poetry run isort credproxy tests

Python Requirements¶

Core Dependencies¶

Flask - Web framework for API endpoints
boto3 / botocore - AWS SDK
PyYAML - Configuration file parsing
jsonschema - Configuration validation
watchdog - File monitoring for dynamic services (optional)
prometheus-client - Metrics export

Optional Dependencies¶

sphinx - Documentation generation
pytest - Testing framework
black / isort - Code formatting

Configuration¶

After installation, create a configuration file:

# config.yaml
server:
  host: localhost
  port: 1338

services:
  my-app:
    auth_token: "your-secure-token"
    source_credentials:
      region: "us-west-2"
    assumed_role:
      RoleArn: "arn:aws:iam::123456789012:role/MyRole"

See Configuration for complete configuration options.

Verification¶

Verify the installation:

# Check health endpoint
curl http://localhost:1338/health

# Expected response:
# {"status": "healthy", "services": {"my-app": "active"}}

Next Steps¶

Review Configuration for configuration options
Check Environment Variables Reference for environment variable support
See Security Policy for security best practices
Read Health Check Configuration for health check configuration
Explore Development for development workflows