API Gateway Proxy Localhost | Complete Local Setup Tutorial

Quick Start

Get your API gateway proxy running on localhost in under 5 minutes.

Clone or download the gateway configuration

git clone https://github.com/example/api-gateway-config.git
cd api-gateway-config

Create environment file

cp .env.example .env
# Edit .env with your API keys

Start the gateway
```
docker-compose up -d
```
Verify it's running
```
curl http://localhost:8080/health
```

Localhost Configuration

Essential configuration options for localhost development:

config.yaml

server:
  host: 127.0.0.1
  port: 8080
  admin_port: 9090

logging:
  level: debug
  format: console

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    base_url: https://api.openai.com/v1
    
rate_limiting:
  enabled: true
  requests_per_minute: 100
  
cache:
  enabled: true
  backend: redis
  url: redis://localhost:6379

Environment Variables

.env

OPENAI_API_KEY=sk-your-key-here
GATEWAY_SECRET=dev-secret-change-in-production
LOG_LEVEL=debug
REDIS_URL=redis://localhost:6379

Port Configuration

Default ports and how to customize them:

Port	Purpose	Config Key
8080	HTTP API endpoint	server.port
8443	HTTPS API endpoint	server.https_port
9090	Admin API	server.admin_port
6379	Redis cache	cache.url

Changing Default Ports

# In docker-compose.yml
services:
  api-gateway:
    ports:
      - "3000:8080"  # Map to localhost:3000
      - "9443:8443"  # HTTPS on localhost:9443

Port Conflicts If port 8080 is already in use, check what's running: lsof -i :8080 or change the gateway port in your configuration.

Local Security Settings

Security configurations specific to localhost development:

CORS for Local Development

cors:
  enabled: true
  origins:
    - "http://localhost:3000"
    - "http://localhost:5173"
    - "http://127.0.0.1:5500"
  methods:
    - GET
    - POST
    - PUT
    - DELETE
  headers:
    - Authorization
    - Content-Type

Local Authentication

For development, use simple API key authentication:

authentication:
  type: api_key
  keys:
    - name: dev-key
      key: dev-secret-key-123
      scopes: ["read", "write"]

Development vs Production Never use development keys or CORS settings in production. Always use environment-specific configurations.

Troubleshooting Common Issues

Gateway Won't Start

# Check logs for errors
docker-compose logs api-gateway

# Verify config syntax
docker-compose config

# Rebuild container
docker-compose up -d --build

Connection Refused

# Verify gateway is running
docker-compose ps

# Check if port is listening
netstat -an | grep 8080

# Test local connection
curl -v http://127.0.0.1:8080/health

Redis Connection Issues

# Check Redis status
docker-compose ps redis

# Test Redis connection
docker-compose exec redis redis-cli ping

# Restart Redis
docker-compose restart redis

API Key Errors

# Verify environment variables are set
docker-compose exec api-gateway env | grep API_KEY

# Check .env file is loaded
cat .env

Useful Local Commands

Health Check

curl http://localhost:8080/health/live
curl http://localhost:8080/health/ready

View Metrics

curl http://localhost:9090/metrics

Test API Call

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer dev-secret-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Stop Everything

docker-compose down
# Remove volumes for clean slate
docker-compose down -v