# Tile Proxy Docker Compose

This directory contains the Docker Compose configuration for deploying the StellaOps Tile Proxy service.

## Overview

The Tile Proxy acts as a caching intermediary between StellaOps clients and upstream Rekor transparency logs. It provides:

- **Tile Caching**: Caches tiles locally for faster subsequent requests
- **Request Coalescing**: Deduplicates concurrent requests for the same tile
- **Offline Support**: Serves from cache when upstream is unavailable
- **TUF Integration**: Optional validation using TUF trust anchors

## Quick Start

```bash
# Start with default configuration
docker compose up -d

# Check health
curl http://localhost:8090/_admin/health

# View cache statistics
curl http://localhost:8090/_admin/cache/stats
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `REKOR_UPSTREAM_URL` | Upstream Rekor URL | `https://rekor.sigstore.dev` |
| `REKOR_ORIGIN` | Log origin identifier | `rekor.sigstore.dev - 1985497715` |
| `TUF_ENABLED` | Enable TUF integration | `false` |
| `TUF_ROOT_URL` | TUF repository URL | - |
| `TUF_VALIDATE_CHECKPOINT` | Validate checkpoint signatures | `true` |
| `CACHE_MAX_SIZE_GB` | Maximum cache size | `10` |
| `CHECKPOINT_TTL_MINUTES` | Checkpoint cache TTL | `5` |
| `SYNC_ENABLED` | Enable scheduled sync | `true` |
| `SYNC_SCHEDULE` | Sync cron schedule | `0 */6 * * *` |
| `SYNC_DEPTH` | Entries to sync tiles for | `10000` |
| `LOG_LEVEL` | Logging level | `Information` |

### Using a .env file

Create a `.env` file to customize configuration:

```bash
# .env
REKOR_UPSTREAM_URL=https://rekor.sigstore.dev
CACHE_MAX_SIZE_GB=20
SYNC_ENABLED=true
SYNC_SCHEDULE=0 */4 * * *
LOG_LEVEL=Debug
```

## API Endpoints

### Proxy Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /tile/{level}/{index}` | Get a tile (cache-through) |
| `GET /tile/{level}/{index}.p/{width}` | Get partial tile |
| `GET /checkpoint` | Get current checkpoint |

### Admin Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /_admin/cache/stats` | Cache statistics |
| `GET /_admin/metrics` | Proxy metrics |
| `POST /_admin/cache/sync` | Trigger manual sync |
| `DELETE /_admin/cache/prune` | Prune old tiles |
| `GET /_admin/health` | Health check |
| `GET /_admin/ready` | Readiness check |

## Volumes

| Volume | Path | Description |
|--------|------|-------------|
| `tile-cache` | `/var/cache/stellaops/tiles` | Cached tiles |
| `tuf-cache` | `/var/cache/stellaops/tuf` | TUF metadata |

## Integration with StellaOps

Configure your StellaOps Attestor to use the tile proxy:

```yaml
attestor:
  rekor:
    url: http://tile-proxy:8080
    # or if running standalone:
    # url: http://localhost:8090
```

## Monitoring

### Prometheus Metrics

The tile proxy exposes metrics at `/_admin/metrics`:

```bash
curl http://localhost:8090/_admin/metrics
```

Example response:
```json
{
  "cacheHits": 12450,
  "cacheMisses": 234,
  "hitRatePercent": 98.15,
  "upstreamRequests": 234,
  "upstreamErrors": 2,
  "inflightRequests": 0
}
```

### Health Checks

```bash
# Liveness (is the service running?)
curl http://localhost:8090/_admin/health

# Readiness (can it serve requests?)
curl http://localhost:8090/_admin/ready
```

## Troubleshooting

### Cache is not being used

1. Check cache stats: `curl http://localhost:8090/_admin/cache/stats`
2. Verify cache volume is mounted correctly
3. Check logs for write errors

### Upstream connection failures

1. Check network connectivity to upstream
2. Verify `REKOR_UPSTREAM_URL` is correct
3. Check for firewall/proxy issues

### High memory usage

1. Reduce `CACHE_MAX_SIZE_GB`
2. Trigger manual prune: `curl -X DELETE http://localhost:8090/_admin/cache/prune?targetSizeBytes=5368709120`

## Development

Build the image locally:

```bash
docker compose build
```

Run with local source:

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```