Infrastructure: Deploy Unleash feature flag platform

[wax911]

Infrastructure: Unleash Deployment & Integration

Overview

Deployment plan for Unleash as the feature flagging backend for on-the-edge and other Local-Stack services. This work runs in parallel with the on-the-edge adapter implementation.

Current State

• GrowthBook: Running as Docker service in platform.yml stack (v4.3.0)
• Database: PostgreSQL already in infrastructure.yml (shared)
• Networking: Traefik for routing, shared network (traefik-public)
• Observability: OTEL collectors integrated

Deployment Plan

Phase 1: Create Unleash Service

Directory Structure:

unleash/
├── docker-compose.yml
├── swarm.fragment.yml
├── .env.example
├── README.md
└── config/
    ├── initial-state.json
    └── healthcheck.sh

docker-compose.yml Specification:

• Image: unleash/unleash:latest (pinned tag in production)
• Port: 4242 (admin UI + API)
• Database: PostgreSQL connection via infrastructure
• Environment variables for DATABASE_URL, UNLEASH_URL, ADMIN_AUTHENTICATION
• Traefik labels for routing (admin UI + client API)
• Health check: GET /internal/health (10s interval)

Traefik Label Integration:
Services expose themselves via labels (as per local-stack convention):

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.unleash-admin.rule=Host(`unleash.local.stack`) && PathPrefix(`/admin`)"
  - "traefik.http.routers.unleash-admin.service=unleash"
  - "traefik.http.services.unleash.loadbalancer.server.port=4242"
  - "traefik.http.routers.unleash-client.rule=Host(`unleash.local.stack`) && PathPrefix(`/client`)"
  - "traefik.http.routers.unleash-client.service=unleash"

Phase 2: Stack Generation

1. Update stacks/platform.yml to include Unleash service fragment
2. Run ./stackctl.sh generate to merge base services + Unleash
3. Verify rendered stack with proper service integration

Files Modified:

• unleash/swarm.fragment.yml (new)
• stacks/platform.yml (regenerated)

Phase 3: Integration & Testing

Pre-Deployment Validation:

• Connectivity: Unleash → PostgreSQL
• Admin UI: Via Traefik routing
• API Health: GET /internal/health returns 200
• Bootstrap: Create default environment & feature flags

Integration Points:

• on-the-edge SDK routes to unleash.local.stack/client
• Traefik observability integrated with OTEL
• PostgreSQL backups include Unleash DB

Documentation:

• unleash/README.md: Service-specific setup
• docs/experiment-migration.md: Referenced from on-the-edge
• AGENTS.md: Add service ownership reference

Phase 4: Deprecation Plan (post-validation)

Once on-the-edge adapter is validated:

1. Monitor GrowthBook for orphaned traffic
2. Archive GrowthBook service (keep config)
3. Delete GrowthBook Docker image
4. Update deployment docs

Database Setup

PostgreSQL requirement already satisfied by infrastructure.yml.

Add to initialization:

CREATE DATABASE unleash OWNER postgres;

Unleash creates required tables on first startup.

Environment Variables

Add to unleash/.env.example:

DATABASE_URL=postgres://postgres:password@postgres:5432/unleash
UNLEASH_URL=http://unleash:4242
UNLEASH_PORT=4242
ADMIN_AUTHENTICATION=custom
ADMIN_USERNAME=admin
ADMIN_PASSWORD=<generated-at-deploy-time>
UNLEASH_API_TOKEN=<generated-at-deploy-time>
LOG_LEVEL=info
ENVIRONMENT_NAME=local

Observability Integration

• Logs: Docker logs aggregated to OTEL collector
• Metrics: Unleash exports Prometheus metrics (optional)
• Traces: Configure OpenTelemetry exporter in environment

Deployment Steps

cd /path/to/local-stack
./stackctl.sh generate
docker stack deploy -c stacks/platform.yml platform

Verification:

• Check service status: docker service ls | grep unleash
• Access admin UI: https://unleash.local.stack/admin
• Test client API: curl https://unleash.local.stack/client/features
• Check logs: docker service logs platform_unleash

Initial Configuration:

1. Login to admin UI
2. Create default feature flags matching on-the-edge setup
3. Create API token for on-the-edge SDK
4. Test flag evaluation via client API

Dependencies & Blockers

on-the-edge:

• Blocker: Deno SDK validation (spike)
• Dependency: Adapter pattern must be implemented before traffic routing
• Timeline: This deployment can proceed in parallel

local-stack:

• PostgreSQL: ✅ Already exists
• Traefik: ✅ Already exists
• No blockers: Can begin immediately

Success Criteria

• Unleash service folder created with all required files
• stackctl.sh regenerates platform.yml with Unleash
• Admin UI accessible via Traefik
• Client API responding at /client/features
• PostgreSQL connectivity verified
• Bootstrap feature flags created (matching GrowthBook setup)
• Documentation complete
• Health checks passing

Related Issues

• on-the-edge Deno SDK spike: Research: Evaluate Unleash as GrowthBook replacement on-the-edge#368
• on-the-edge adapter implementation: (follows spike results)

References

• Unleash Docs: https://docs.getunleash.io/deploy/docker
• Unleash Docker Hub: https://hub.docker.com/r/unleash/unleash
• Local-Stack structure: See AGENTS.md
• Traefik label reference: docker-compose.yml examples in existing services
• PostgreSQL setup: postgres/ service folder

Notes

• Unleash is lightweight (~500MB Docker image)
• No new dependencies beyond PostgreSQL (exists)
• GrowthBook + Unleash can run in parallel during validation
• Migration is non-breaking via adapter pattern

[wax911]

Related SDK Work

on-the-edge Deno SDK Validation: AniTrend/on-the-edge#368

This infrastructure issue is designed to run in parallel with the SDK evaluation spike on on-the-edge. The critical blocker is validating Unleash JS SDK compatibility with Deno.

Dependency Chain:

1. ✅ Research complete (this issue, linked SDK issue)
2. ⏳ Spike validation → go/no-go decision (on-the-edge side, 4-6 hrs)
3. ⏳ Infrastructure deployment (this issue, 2-3 days - can start independently)
4. ⏳ Adapter implementation (5-7 days, post-spike)
5. ⏳ Traffic routing & validation (1+ week)

Timeline: Phases 1-2 of this deployment can proceed immediately (service creation + stack generation). Phase 3 integration testing waits for adapter validation from on-the-edge side.