Hosting Service Setup

Hosting Service Overview

Audience: Platform teams setting up production hosting infrastructure for their organization.

Your 1fe application shell needs to be hosted on a reliable service that can handle user traffic and serve your application globally. This guide covers how to deploy your 1fe instance to production hosting services.

Why You Need a Hosting Service

A hosting service provides:

• Application shell hosting - Serves your main 1fe application
• Static file serving - HTML, CSS, JS files for your shell
• Global availability - Ensures your app is accessible worldwide
• SSL/TLS termination - Secure HTTPS connections
• Load balancing - Handle traffic spikes and ensure reliability

Hosting Service Options

Azure Web App

Who is this for? This guide demonstrates setup with Azure Web App, but you can use any of the other hosting providers listed at the end of this page—such as AWS, Google Cloud, Vercel, Netlify, or traditional servers—based on your organization’s needs.

This guide provides instructions for creating and configuring an Azure Web App for your 1fe application.

Step 1: Introduction to Azure App Service

Azure App Service is a Platform-as-a-Service (PaaS) for hosting web applications, REST APIs, and mobile backends. See the official Azure App Service documentation for a comprehensive overview.

Official Documentation:

• Create a Node.js web app in Azure
• Azure App Service pricing

Step 2: Create a New Web App

To begin, follow the official Azure documentation to create a new Web App: Quickstart: Create a Node.js web app in Azure.

Use the following template configuration values to match the recommended setup for your 1fe application:

Template Configuration Values:

Setting	Example Value	Description
Subscription	Choose from dropdown	Select your Azure subscription
Resource Group	1fe-demo-rg	Logical container for resources
Web App Name	1fe-demo	Globally unique name
Publish	Code	Publishing method
Runtime Stack	Node 22-LTS	Node.js runtime version
Operating System	Linux	Recommended for Node.js
Region	Central US	Choose region close to users

Setup Instructions:

1. Go to the Azure Portal:
   https://portal.azure.com/

2. Create a new resource:
   Click + Create a resource on the home page.

3. Select Your Subscription

   • Choose your Azure subscription from the dropdown

4. Configure Resource Group

   • Select an existing resource group or create a new one (e.g., 1fe-demo-rg)

5. Set Web App Name

   • Enter a globally unique name for your web app (e.g., 1fe-demo)

Important: Web App URL

The name you choose will be part of the default URL (e.g., 1fe-demo.azurewebsites.net). Choose a descriptive and globally unique name.

6. Configure Publishing Method

   • Publish: Select Code

7. Select Runtime Stack

   • Runtime stack: Select the appropriate runtime (e.g., Node 22-LTS)

8. Choose Operating System

   • Operating System: Select Linux

9. Select Region

   • Region: Select a region close to your users (e.g., Central US)

10. Proceed to Deployment Configuration

    • Click Next: Deployment to continue

Step 3: Configure Deployment from GitHub

To enable continuous deployment from a GitHub repository, follow the steps in the official Azure documentation for connecting your web app to GitHub. This ensures your app is automatically updated with every push.

Setup Instructions:

1. Navigate to Deployment Tab
   On the Deployment tab during Web App creation (or by navigating to Deployment Center for an existing app)

2. Enable Continuous Deployment
   Set Continuous deployment to Enable

3. Select GitHub as Source
   Source: Select GitHub

4. Authorize Azure to Access GitHub
   You may need to authorize Azure to access your GitHub account
   Follow the prompts to sign in to GitHub

5. Grant Necessary Permissions
   Grant the necessary permissions when prompted

6. Select Your GitHub Organization
   Organization: Select your GitHub organization from the dropdown

7. Choose Your Repository
   Repository: Select the repository containing your application code

8. Select Deployment Branch
   Branch: Select the branch you want to deploy from (e.g., main or production)

9. Review and Create Web App
   Click Review + create to review all settings

10. Complete Web App Creation
    Click Create to create the Web App
    Azure will automatically generate a GitHub Actions workflow file in your repository to handle deployments

Example Implementation: 1fe Starter App CI Workflow

GitHub Secrets Configuration for the 1fe Starter App CI Workflow

Your CI/CD workflow requires several secrets to deploy to Azure Web App hosting. These secrets are referenced in the 1fe-starter-app CI workflow:

SSH_PRIVATE_1FE: ${{ secrets.SSH_PRIVATE_1FE }}
AKAMAI_NS_SSH_PRIVATE_KEY: ${{ secrets.AKAMAI_NS_SSH_PRIVATE_KEY }}
AZUREAPPSERVICE_CLIENTID: ${{ secrets.AZUREAPPSERVICE_CLIENTID }}
AZUREAPPSERVICE_TENANTID: ${{ secrets.AZUREAPPSERVICE_TENANTID }}
AZUREAPPSERVICE_SUBSCRIPTIONID: ${{ secrets.AZUREAPPSERVICE_SUBSCRIPTIONID }}
AZURE_RESOURCE_GROUP: ${{ secrets.AZURE_RESOURCE_GROUP }}
NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY_1FE }}

Required Secrets

Azure Web App Deployment:

• AZUREAPPSERVICE_CLIENTID - Service Principal Client ID for Azure authentication
• AZUREAPPSERVICE_TENANTID - Azure AD Tenant ID
• AZUREAPPSERVICE_SUBSCRIPTIONID - Your Azure Subscription ID
• AZURE_RESOURCE_GROUP - Resource group containing your Azure Web App

SSH Keys:

• SSH_PRIVATE_1FE - Private SSH key for deployment access
• AKAMAI_NS_SSH_PRIVATE_KEY - Akamai NetStorage SSH private key for CDN uploads

Package Registry:

• NPM_TOKEN_READONLY - Read-only NPM token for accessing private packages

How to Configure Secrets

1. Navigate to Repository Settings
   Go to your GitHub repository → Settings → Secrets and variables → Actions

2. Add Each Secret
   Click “New repository secret” and add each secret with the exact name shown above

3. Obtain Secret Values:

Azure Service Principal Credentials:

To get the Azure secrets, you need to create a Service Principal and gather Azure subscription information:

Via Azure CLI:

# Login to Azure
az login

# Get your subscription ID
az account show --query id --output tsv

# Get your tenant ID
az account show --query tenantId --output tsv

# Create Service Principal with Contributor role
az ad sp create-for-rbac --name "1fe-deployment-sp" \
  --role contributor \
  --scopes /subscriptions/{your-subscription-id}/resourceGroups/{your-resource-group-name}

This command outputs JSON containing your AZUREAPPSERVICE_CLIENTID (appId) and creates the service principal.

Via Azure Portal:

1. Subscription ID: Azure Portal → Subscriptions → Copy your subscription ID
2. Tenant ID: Azure Portal → Azure Active Directory → Properties → Directory ID
3. Service Principal: Azure Portal → Azure Active Directory → App registrations → New registration
4. Resource Group: The name of your existing Azure resource group containing your Web App

Other Credentials:

• SSH keys: Generate using ssh-keygen -t rsa -b 4096 or obtain from your infrastructure team
• NPM token: Create in NPM registry settings or obtain from your DevOps team

Team Coordination

These secrets may already be configured by your DevOps or infrastructure team. Check with them before creating new credentials to avoid duplicating access keys.

Step 4: Add and Configure a Custom Domain

Your Web App has a default domain (e.g., 1fe-demo.azurewebsites.net), but you will likely want to use a custom domain. Refer to Official Documentation: Set up an existing custom domain name for your app

Setup Instructions:

1. Navigate to Your Web App Resource
   In the Azure Portal, navigate to your Web App resource

2. Access Custom Domains Section
   In the left-hand menu, select Custom domains

3. Start Adding Custom Domain
   Click + Add custom domain

4. Select Your DNS Provider
   Domain provider: Select your DNS provider (e.g., GoDaddy, Cloudflare)

5. Enter Your Domain Name
   Enter the domain name you want to use (e.g., demo.yourdomain.com)

6. Review DNS Record Requirements
   The portal will provide you with DNS record information to validate ownership

7. Create Required DNS Records
   Create a TXT and/or a CNAME record with your domain registrar using the DNS information provided by Azure

8. Validate Domain Ownership
   Once the DNS records are created, click Validate in the Azure Portal

9. Complete Domain Addition
   After validation is successful, click Add custom domain

App Service Plan Requirement

Your App Service plan must be a paid tier (e.g., Basic, Standard, Premium) to add a custom domain. The Free (F1) and Shared (D1) tiers do not support custom domains.

Step 5: Configure Environment Variables

Environment variables (known as “Application settings” in Azure) are a secure way to manage configuration values, such as API keys or database connection strings, without hard-coding them into your application. Official Documentation: Configure an App Service App - Environment variables

Required Environment Variables for 1FE Starter App in Azure Web App:

Environment Variable Name	Example Value	Purpose & Meaning
APPLICATIONINSIGHTS_CONNECTION_STRING	InstrumentationKey=12345678-1234-5678-9abc-123456789012;IngestionEndpoint=https://...	Application Insights: Connection string for telemetry and performance monitoring in Azure
ApplicationInsightsAgent_EXTENSION_VERSION	~3	App Service Extension: Version of Application Insights agent extension for automatic telemetry collection
AZURE_APPCONFIG_CONNECTION_STRING	Endpoint=https://yourconfig.azconfig.io;Id=...;Secret=...	Configuration Service: Connection string to Azure App Configuration for dynamic widget settings
BUILD_NUMBER	20241201.1	Deployment Tracking: Build identifier for tracking which version is deployed, typically set by CI/CD pipeline
GITHUB_RUN_ID	123456789	CI/CD Tracking: GitHub Actions run identifier for deployment traceability and debugging
NODE_ENV	production	Runtime Environment: Tells Node.js to run in production mode, enabling performance optimizations
XDT_MicrosoftApplicationInsights_Mode	Recommended	Application Insights: Configures the monitoring level for Azure Application Insights integration

Setup Instructions:

1. Navigate to Your Web App Resource
   In the Azure Portal, navigate to your Web App resource.

2. Access Configuration Section
   In the left-hand menu, select Configuration.

3. Open Application Settings Tab
   On the Application settings tab, click + New application setting.

4. Enter Variable Name and Value

5. Confirm Variable Addition
   Click OK to confirm the new setting.

6. Save Configuration Changes
   Click Save at the top of the page.

7. Wait for App Restart
   The app will restart automatically to apply the new settings.

App Restart Required

The app will restart automatically when you save new application settings. Plan configuration changes during appropriate maintenance windows.

Other Hosting Providers

Coming Soon

If you are using a different hosting provider, you can follow the same steps to configure your environment variables.

Here are some other hosting providers you can consider:

• AWS (Amazon Web Services) - EC2, Elastic Beanstalk, and Lambda deployment guides
• Google Cloud Platform - App Engine and Compute Engine setup
• Vercel - Serverless deployment for 1fe applications
• Netlify - Static site hosting with CI/CD integration

Check back soon for detailed setup guides for these platforms.

Next Steps

After setting up hosting:

1. Configure CDN for Widget Bundles
2. Set up Configuration Service
3. Set up NPM Registry
4. Set up CI/CD Pipeline