git.stella-ops.org/devops/compose/tile-proxy/README.md

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

# 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:

# .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:

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:

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

Example response:

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

Health Checks

# 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:

docker compose build

Run with local source:

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