Configuring the New Hub Region in GKL API

Overview

A new hub region is added to the GKL Platform through a MongoDB migration. You write a new migration script in the API repository based on a previous one, commit it, then run it against the production database via Studio 3T on the EC2 desktop. Finally you adjust the new region’s web environment configuration and the go-live flags. The migration does two things:

Pushes a new entry into the REGION_CONFIGURATION document with the new hub’s settings.
Copies an existing hub’s other configuration documents (such as its WEB_ENVIRONMENT_CONFIGURATION) and re-inserts them with the new hub code in the _id.

Because step 2 copies an existing hub verbatim, you then edit the new region’s WEB_ENVIRONMENT_CONFIGURATION document to set the correct values for the new hub.

You are working directly on the PROD database. GklPlatform_PROD holds live data that powers sales and other applications for the hubs currently running. A mistake here can disrupt active hubs. Work carefully, only touch the documents this SOP describes, and double check every value before running anything.

Prerequisites

Gather the following values before starting. They populate the new region entry and the web environment configuration:

Value	Details
Hub code (region code, uppercase)	For example `DE`. See the naming convention.
Currency	For example `EUR`. Confirm with the Finance Team.
Display name	For example `Germany`.
Vivenu base URL	Always `https://vivenu.com`. This SOP only ever references PROD.
Vivenu API key	The GKL Platform key from the API Key SOP.
HMAC secret	Generate it now, for example via jwtsecretkeygenerator.com. It must be generated here because it is created before the webhooks. The base64 encoded value is later pasted into the webhooks.
Teams webhook URL	The incoming webhook URL from the Teams Notification SOP.
Operator dashboard URL	Always `https://admin.uk.fat-kartingleague.com`. The `uk` is from legacy infrastructure.
Base website URL	For example `https://events.fat-kartingleague.com/DE`.
Redirect URLs	Event listing, privacy, terms, ready-to-race, landing page.

Creating the Migration Script

Open the Migrations folder

In the API repository, go to GklPlatform.API/DbScripts/Migrations. The migrations are numbered .js MongoDB scripts.

Copy the most recent add-hub migration

Copy the latest add-hub migration (for example 033_add_germany_hub.js) to a new file, incrementing the number prefix and naming it for the new hub, for example 034_add_<hub>_hub.js.

Change the parameters for the new hub

Update the values in the REGION_CONFIGURATION push to match the new hub. Only the parameters change, the logic stays the same:

db.getCollection("Configurations").updateOne({ _id: "REGION_CONFIGURATION" }, {
    $push: {
        Configuration: {
            "id": "DE",
            "currency": "EUR",
            "display": "Germany",
            "isActive": false,
            "vivenuSecret": {
                "BaseUrl": "https://vivenu.com",
                "ApiKey": "<vivenu-api-key>"
            },
            "teamsWebhookUrl": "<teams-webhook-url>",
            "operatorDashboardUrl": "https://admin.uk.fat-kartingleague.com",
            "hmacSecret": "<hmac-secret>",
            "baseWebsiteUrl": "https://events.fat-kartingleague.com/DE",
            "showOnWebsite": false
        }
    }
})

Leave isActive and showOnWebsite as false for now. They are switched on later (see Go-live flags).

Check the copy block

The second block of the script finds an existing hub’s documents and re-inserts them with the new hub code. Make sure it copies from a suitable source hub and writes to the new code, for example:

var sourceConfigs = db.getCollection("Configurations").find({ _id: /UK/ }).toArray();
for (var c of sourceConfigs) {
    c._id = c._id.replace("UK", "DE");
    db.getCollection("Configurations").insertOne(c);
}

You can change individual values in the copied documents later, for example the currency in the WEB_ENVIRONMENT_CONFIGURATION document and the event types.

Commit and push

Save the new migration, then commit and push it to the repository.

Never commit real secrets to the repository. This is why the committed migration scripts keep placeholders (for example <vivenu-api-key> and <hmac-secret>) and point at DEV values. The real PROD secrets and URLs are only substituted in when you paste the migration into Studio 3T, never in the committed file.

Running the Migration on PROD

Previous migrations may point to DEV. For example, 033_add_germany_hub.js uses https://vivenu.dev, a events-dev-v2 base website URL, and a .dev operator dashboard URL. Before running against PROD, change every DEV value to its PROD equivalent (for example https://vivenu.com and the production website and dashboard URLs).

Copy the migration script

Copy the full contents of your new migration script.

Connect to the EC2 desktop and open Studio 3T

Connect to the EC2 desktop, open Studio 3T, and connect to the Mongo instance.

Open the Configurations collection

Open the GklPlatform_PROD database, then open the Configurations collection.

Paste and run the migration

Paste the migration into the shell for the Configurations collection and run it. Confirm any DEV values have been changed to PROD before running.

Editing the New Region Web Environment Configuration

Because the copy block duplicated an existing hub’s documents, the new region’s web environment configuration still holds the source hub’s values. Update it for the new hub.

Find the web environment documents

In the Configurations collection, run a find on _id: /WEB_ENV/.

Open the new hub's document

Identify the new document whose _id prefix is your new hub code, for example WEB_ENVIRONMENT_CONFIGURATION_DE.

Set the currency and other parameters

Edit that document to set the currency and the other hub-specific parameters, such as the redirect URLs (eventListingRedirect, privacyRedirect, termsRedirect, r2rExplanationRedirect, landingPageRedirect). Compare against an existing live hub’s WEB_ENVIRONMENT_CONFIGURATION document to see which values are region-specific.

Go-live Flags

Two flags on the new region entry control when the hub becomes active. Both start as false.

Set isActive to true

Set "isActive": true when you are ready to start ingesting via the Vivenu webhook and want to see the hub on the operational dashboard.

Set showOnWebsite to true

Set "showOnWebsite": true when making a test payment before release, or when the deployment team is ready to release the website to the public.

While showOnWebsite is false, users cannot visit the region’s link or events on our website.

Internal Tools

Third-Party Tools

Developer Docs

Configuring the New Hub Region in GKL API

Overview

Prerequisites

Creating the Migration Script

Running the Migration on PROD

Editing the New Region Web Environment Configuration

Go-live Flags

​Overview

​Prerequisites

​Creating the Migration Script

​Running the Migration on PROD

​Editing the New Region Web Environment Configuration

​Go-live Flags

Overview

Prerequisites

Creating the Migration Script

Running the Migration on PROD

Editing the New Region Web Environment Configuration

Go-live Flags