162 lines
3.9 KiB
Markdown
162 lines
3.9 KiB
Markdown
# 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
|
|
```
|