Launching a Benefits Hub Tenant

Step-by-step guide to launch a new Benefits Hub tenant on the shared Benefits Hub VM.

Prerequisites

Before starting a launch, confirm the following:

The partner’s HA Admin Portal tenant is already launched and operational
Tenant name confirmed (lowercase identifier used in resource naming, e.g., simpra)
Tenant display name confirmed (e.g., Simpra)
Subdomain decided (pattern: <tenant>benefits)

The HA platform and tenant must already be launched. Benefits Hub depends on the Django HomeAlign backend for its API and authentication. If the HA tenant doesn’t exist yet, follow the HA Admin Portal launch runbook first.

Phase 1: Setup Partner in Django HomeAlign

Step 1: Run the Tenant Database Script

Follow the How to Add a New DB Connection When Adding a Tenant guide in the django_homealign repo.

The repo provides an interactive script that handles the setup:

./add_new_tenant_database.sh

The script prompts for the UAT database name, production database name, database alias, frontend display name, database user, and DB hosts. It automatically modifies environment files, Django settings, the frontend database selector, and Docker Swarm secret definitions.

Step 2: Complete Post-Script Steps

Review all changes — compare against the reference PR
Add the WEB_DB_PASS secret to the GCP Secret Manager vaults for both django_homealign and eligibility_service:
- Staging:
  - django-ha-vault
  - eligibility-service-vault
- Production:
  - django-ha-vault
  - eligibility-service-vault
Review client_config.json and add the new tenant
Create a PR, deploy, and test on staging by selecting the new database in the frontend dropdown

Phase 2: Add App Config in Infrahive

Benefits Hub tenants share a single VM. Launching a new tenant means adding an app entry to the hb-infra tfvars files, which provisions Cloudflare DNS records, tunnels, and Ansible deployment configuration.

Step 3: Add App Entry to Non-Production

Edit infra/hb-infra/non-production.auto.tfvars and add a new entry to the apps list:

{
  name                   = "<TENANT>-benefits-platform"
  ansible_name           = "<TENANT>-benefits-platform"
  vm_resource_name       = "benefits-hub"
  db_resource_name       = ""
  public_container_name  = "ui"
  admin_container_name   = "ui"
  github_repo            = "git@github.com:thehelperbees/benefits-platform.git"
  github_short_repo      = "benefits-platform"
  docker_container_abbrv = "benefits-platform"
  docker_image           = "benefits-platform/ui"
  docker_stack_name      = "<TENANT>_benefits_platform"
  docker_compose_version = "3.9"
  docker_secret_file     = ""
  ping_route             = "/api/ping"
  app_env                = "<TENANT>-staging"
  dashboard_name         = "<TENANT_DISPLAY> Benefits Platform"
  domains = [
    {
      name               = "thb.sh"
      cloudflare_zone_id = "<NON_PROD_ZONE_ID>"
      subdomains = [
        {
          "type" : "admin"
          "name" : "<TENANT>benefits"
          "access_policies" : ["thb_email", "vpn_bypass"]
        },
      ]
    }
  ]
  public_site_urls = []
  admin_site_urls  = ["<TENANT>benefits.thb.sh"]
  enable_ws : false
  enable_gql : false
  enable_flower : false
  enable_camunda : false
},

Step 4: Add App Entry to Production

Edit infra/hb-infra/production.auto.tfvars with the production variant. Key differences from non-production:

{
  name                   = "<TENANT>-benefits-platform"
  ansible_name           = "<TENANT>-benefits-platform"
  vm_resource_name       = "benefits-hub"
  db_resource_name       = ""
  public_container_name  = "ui"
  admin_container_name   = "ui"
  github_repo            = "git@github.com:thehelperbees/benefits-platform.git"
  github_short_repo      = "benefits-platform"
  docker_container_abbrv = "benefits-platform"
  docker_image           = "benefits-platform/ui"
  docker_stack_name      = "<TENANT>_benefits_platform"
  docker_compose_version = "3.9"
  ping_route             = "/api/ping"
  app_env                = "<TENANT>-production"
  dashboard_name         = "<TENANT_DISPLAY> Benefits Platform"
  domains = [
    {
      name               = "thb.nu"
      cloudflare_zone_id = "<PROD_ZONE_ID_THB_NU>"
      subdomains = [
        {
          "type" : "public"
          "name" : "<TENANT>benefits"
          "access_policies" : []
        }
      ]
    },
    {
      name               = "thehelperbees.com"
      cloudflare_zone_id = "<PROD_ZONE_ID_THB_COM>"
      subdomains = [
        {
          "type" : "public"
          "name" : "<TENANT>benefits"
          "access_policies" : []
        }
      ]
    }
  ]
  public_site_urls = ["<TENANT>benefits.thehelperbees.com"]
  admin_site_urls  = ["<TENANT>benefits.thb.nu"]
  enable_ws : false
  enable_gql : false
  enable_flower : false
  enable_camunda : false
},

Fields that change per tenant:

Field	Pattern
`name` / `ansible_name`	`<tenant>-benefits-platform`
`docker_stack_name`	`<tenant>_benefits_platform` (underscores)
`app_env`	`<tenant>-staging` (non-prod) / `<tenant>-production` (prod)
`dashboard_name`	`<TenantDisplay> Benefits Platform`
`domains` / URLs	Subdomain is `<tenant>benefits` (no separator)

Non-prod vs prod differences:

Aspect	Non-production	Production
Domain(s)	`thb.sh`	`thb.nu` + `thehelperbees.com`
Subdomain type	`"admin"`	`"public"`
Access policies	`["thb_email", "vpn_bypass"]`	`[]` (open access)
`docker_secret_file`	`""` (present)	absent
`public_site_urls`	`[]`	`["<tenant>benefits.thehelperbees.com"]`
`admin_site_urls`	`["<tenant>benefits.thb.sh"]`	`["<tenant>benefits.thb.nu"]`

Convention: Copy the Cloudflare zone IDs from an existing benefits-platform entry in the same tfvars file.

Phase 3: Release and Build Infrastructure

Step 5: Create a PR and Deploy

Create a branch and commit the tfvars changes
Open a PR targeting the plan branch
After PR approval, merge into plan
Deploy a release

What gets provisioned:

Cloudflare tunnel routes and DNS records for the new subdomain(s)
Cloudflare Access policies (non-production only)
GCP Secret Manager vault for the app
Ansible config YAML uploaded to GCS bucket (consumed by AWX for deployment)
GCP uptime monitoring (production only)

Verify: Open Cloud Build History and confirm the hb-infra apply completed successfully for each target environment.

Phase 4: Setup Benefits-Platform Environment

Step 6: Add Environment Variables

In the benefits-platform repo, create .env files for the new tenant. Each tenant needs two files:

.envs/.<tenant>-staging/.web
.envs/.<tenant>-production/.web

Staging template (.envs/.<tenant>-staging/.web):

API_BASE_URL=https://homealign-dj.thb.sh/core-api
TENANT_LOGIN_URL=https://homealign-dj.thb.sh/tenant-login/
TENANT_REFRESH_URL=https://homealign-dj.thb.sh/tenant-refresh/
IDENTITY_SERVER_URL=https://auth.myhaapp.com
TENANT=<tenant>
POSTHOG_DEBUG=false
POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_KEY=<copy from existing tenant>
SUPPORT_URL=https://<tenant>-thb.zendesk.com/hc/en-us/requests/new

Production template (.envs/.<tenant>-production/.web):

API_BASE_URL=https://homealign-dj.thehelperbees.com/core-api
TENANT_LOGIN_URL=https://homealign-dj.thehelperbees.com/tenant-login/
TENANT_REFRESH_URL=https://homealign-dj.thehelperbees.com/tenant-refresh/
IDENTITY_SERVER_URL=https://auth.myhomealign.com
TENANT=<tenant>
POSTHOG_DEBUG=false
POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_KEY=<copy from existing tenant>
SUPPORT_URL=https://<tenant>-thb.zendesk.com/hc/en-us/requests/new

Only TENANT and SUPPORT_URL are tenant-specific. Copy POSTHOG_KEY from any existing tenant’s .env file. All other values are constant per environment.

Create a PR in the benefits-platform repo. See this commit for a reference example.

Staging subdomain resolves (e.g., <tenant>benefits.thb.sh)
Production subdomain resolves (e.g., <tenant>benefits.thehelperbees.com)
/api/ping health check returns success
Cloudflare Access policies are enforced on staging
Application loads correctly and connects to the correct tenant database
AWX deployment completes successfully in both environments

Edit this page