Self-host the API Management developer portal

APPLIES TO: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

This tutorial describes how to self-host the API Management developer portal. Self-hosting is one of several options to extend the functionality of the developer portal. For example, you can self-host multiple portals for your API Management instance, with different features. When you self-host a portal, you become its maintainer and you're responsible for its upgrades. The developer portal requires the API Management REST API to manage the content.

If you already uploaded or modified media files in the managed portal, see Move from managed to self-hosted, later in this article.

Prerequisites

To set up a local development environment, you need to have:

• An API Management service instance. If you don't have one, see Quickstart - Create an Azure API Management instance.

  If you created your instance in a v2 service tier, first enable the developer portal.

  1. In the sidebar menu, under Developer portal, select Portal settings.
  2. In the Portal settings window, select Enabled. Select Save. It might take a few minutes to enable the developer portal.

• An Azure blob storage account, which you'll use to enable the static websites feature. See Create a storage account.

• Git on your machine. Install it by following this Git tutorial.

• Node.js (Long Term Support (LTS) version, v10.15.0 or later) and npm on your machine. See Downloading and installing Node.js and npm.

• Azure CLI. Follow the Azure CLI installation steps.

• Permissions to create a Microsoft Entra app registration.

Step 1: Set up local environment

To set up your local environment, clone the repository, switch to the latest release of the developer portal, and install npm packages.

1. Clone the api-management-developer-portal repo from GitHub:

   git clone https://github.com/Azure/api-management-developer-portal.git
   

2. Go to your local copy of the repo:

   cd api-management-developer-portal
   

3. Check out the latest release of the portal.

   Before you run the following code, check the current release tag in the Releases section of the repository and replace <current-release-tag> value with the latest release tag.

   git checkout <current-release-tag>
   

4. Install any available npm packages:

   npm install
   

Step 2: Configure JSON files, static website, and CORS settings

config.design.json file

Go to the src folder and open the config.design.json file.

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

In subscriptionId, resourceGroupName, and serviceName, enter values for the subscription, resource group, and service name of your API Management instance. I

Optional settings in config.design.json

Optionally, configure the following settings in the config.design.json file:

1. If you'd like to enable CAPTCHA in your developer portal, set "useHipCaptcha": true. Make sure to configure CORS settings for developer portal backend.

   {
       ...
       "useHipCaptcha": true
       ...
   }
   

2. In integration, under googleFonts, optionally set apiKey to a Google API key that allows access to the Web Fonts Developer API. This key is only needed if you want to add Google fonts in the Styles section of the developer portal editor.

   {
       ...
       "integration": {
           "googleFonts": {
               "apiKey": "< your Google API key >"
           }
       }
       ...
   }
   
   

3. If you don't already have a key, you can configure one using the Google Cloud console. Follow these steps:

   1. Open the Google Cloud console.
   2. Check whether the Web Fonts Developer API is enabled. If it isn't, enable it.
   3. Select Create credentials > API key.
   4. In the open dialog, copy the generated key and paste it as the value of apiKey in the config.design.json file.
   5. Select Edit API key to open the key editor.
   6. In the editor, under API restrictions, select Restrict key. In the dropdown, select Web Fonts Developer API.
   7. Select Save.

config.publish.json file

Go to the src folder and open the config.publish.json file.

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Copy and paste the subscriptionId, resourceGroupName, and serviceName values from the previous configuration file.

config.runtime.json file

Go to the src folder and open the config.runtime.json file.

{
    "environment": "runtime",
    "backendUrl": "https://< service name >.developer.azure-api.net"
}

Substitute < service name > with the name of your API Management instance used in the previous configuration files.

Configure the static website

Configure the Static website feature in your storage account by providing routes to the index and error pages:

1. In the Azure portal, go to your storage account in the Azure portal.

2. In the sidebar menu, select Data management > Static website.

3. On the Static website page, select Enabled.

4. In the Index document name field, enter index.html.

5. In the Error document path field, enter 404/index.html.

6. Select Save.

Take note of the Primary endpoint URL. You'll configure it later to access your self-hosted portal.

Configure CORS settings for storage account

To configure the cross-origin resource sharing (CORS) settings for the storage account:

1. Go to your storage account in the Azure portal.

2. From the sidebar menu, under Settings, select Resource sharing (CORS).

3. In the Blob service tab, configure the following rules:

   Rule	Value
   Allowed origins	*
   Allowed methods	Select all the HTTP verbs.
   Allowed headers	*
   Exposed headers	*
   Max age	0

4. Select Save.

Configure CORS settings for developer portal backend

Configure CORS settings for the developer portal backend to allow requests originating through your self-hosted developer portal. The self-hosted developer portal relies on the developer portal's backend endpoint (set in backendUrl in the portal config.runtime.json file) to enable several features, including:

• CAPTCHA verification
• OAuth 2.0 authorization in the test console
• Delegation of user authentication and product subscription

To add CORS settings:

1. Go to your API Management instance in the Azure portal.
2. In the sidebar menu, select Developer portal > Settings.
3. On the Self-hosted portal configuration tab, add one or more Origin domain values. For example:
   • The domain where the self-hosted portal is hosted, such as https://contoso.developer.azure-api.net
   • localhost for local development (if applicable), such as http://localhost:8080 or https://localhost:8080
4. Select Save.

Step 3: Run the portal

Now you can build and run a local portal instance in the development mode. In development mode, all the optimizations are turned off and the source maps are turned on.

1. Run the following command:

   npm run start
   

2. You're prompted to authenticate via your browser. Select your Microsoft credentials to continue.

3. After some time, the default browser automatically opens with your local developer portal instance. The default address is http://localhost:8080, but the port can change if 8080 is already occupied. When you make changes to the codebase of the project, it triggers a rebuild and refreshes your browser window.

Step 4: Edit through the visual editor

Use the visual editor to carry out these tasks:

• Customize your portal
• Author content
• Organize the structure of the website
• Stylize its appearance

See Tutorial: Access and customize the developer portal. It covers the basics of the administrative user interface and lists recommended changes to the default content. Save all changes in the local environment, and press Ctrl+C to close it.

Step 5: Publish the portal locally

1. Run npm run publish. You're prompted to authenticate via your browser. Select your Microsoft credentials to continue.

2. After some time, the content is published to the dist/website folder.

Step 6: Upload static files to a blob

Use the Azure CLI to upload the locally generated static files to a blob, and make sure your visitors can get to them:

1. Open Windows Command Prompt, PowerShell, or other command shell.

2. Run the following az storage blog upload-batch command. Replace <connection-string> with a connection string for your storage account. You can get it from the Security + networking > Access keys section of your storage account.

   az storage blob upload-batch --source dist/website \
       --account-name <your-storage-account-name> \
       --destination '$web' \
       --connection-string "<connection-string>"
   

Step 7: Go to your website

Your website is now live under the hostname specified in your Azure Storage properties. In the sidebar menu, go to Data management > Static website. The hostname is the value of Primary endpoint.

Host the website editor

When making changes in website code, you may need to update the website editor code as well to be able to properly support editing of your modified widgets. In this case, besides hosting the portal, you may also want to host the editor application. For this, you need to build it and configure to access your API Management service.

For this, you need a Microsoft Entra ID application in your tenant:

1. Register an application in your Microsoft Entra ID tenant. Take note of the Application (client) ID and the Directory (tenant) ID. You configure them in a later step.
2. Configure a Web Redirect URI (reply URL) in this application to point to the endpoint of the web app where the designer is hosted. This is typically the location of the blob storage-based website. Example: https://<your-storage-account-name>z13.web.core.windows.net/.
3. If you want to publish the portal in pipelines (GitHub Actions), also create a client secret for this application. Take note of the generated secret value and store it in a safe location.

Then, follow these steps to host the website editor:

1. Add clientId and tenantId fields to the config.design.json file.

   {
       ...
       "clientId": "< Entra ID app ID >",
       "tenantId": "< Entra ID tenant ID >"
       ...
   }
   

2. Run the npm run build-designer command to build designer.

3. Go to the generated /dist/designer folder, which contains a file config.json with the following content:

   {
       "subscriptionId": "< subscription ID >",
       "resourceGroupName": "< resource group name >",
       "serviceName": "< API Management service name >",
       "clientId": "< Entra ID client ID >",
       "tenantId": "< Entra ID tenant ID >"
   }
   

4. Confirm the configuration of subscriptionId, resourceGroupName and serviceName, which are needed to connect to your API Management service using Azure Resource Manager APIs.

Publish portal in pipelines (GitHub Actions)

You can publish the self-hosted portal in a pipeline such as GitHub Actions.

The pipeline also needs Entra ID application credentials to execute publishing using pipelines. You can use the same Entra ID application described in the previous steps. The tenantId, clientId, and especially clientSecret must be kept in respective key storage. See Using secrets in GitHub Actions for more details.

Example of GitHub Actions pipeline YAML:

name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

Change API Management notification templates

Replace the developer portal URL in the API Management notification templates so that it points to your self-hosted portal. See How to configure notifications and email templates in Azure API Management.

In particular, carry out the following changes to the default templates:

Email change confirmation

Update the developer portal URL in the Email change confirmation notification template:

Original content

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Updated

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

New developer account confirmation

Update the developer portal URL in the New developer account confirmation notification template:

Original content

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Updated

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Invite user

Update the developer portal URL in the Invite user notification template:

Original content

<a href="$ConfirmUrl">$ConfirmUrl</a>

Updated

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

New subscription activated

Update the developer portal URL in the New subscription activated notification template:

Original content

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Updated

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Original content

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Updated

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Original content

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Updated

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Original content

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Updated

<!--Remove the entire block of HTML code above.-->

Password change confirmation

Update the developer portal URL in the Password change confirmation notification template:

Original content

<a href="$DevPortalUrl">$DevPortalUrl</a>

Updated

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

All templates

Update the developer portal URL in any template that has a link in the footer:

Original content

<a href="$DevPortalUrl">$DevPortalUrl</a>

Updated

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Move from managed to self-hosted developer portal

Over time, your business requirements might change. You can end up in a situation where the managed version of the API Management developer portal no longer satisfies your needs. For example, a new requirement might force you to build a custom widget that integrates with a third-party data provider. Unlike the managed version, the self-hosted version of the portal offers you full flexibility and extensibility.

Transition process

You can transition from the managed version to a self-hosted version within the same API Management service instance. The process preserves the modifications that you carried out in the managed version of the portal. Make sure you back up the portal's content beforehand. You can find the backup script in the scripts.v3 folder of the API Management developer portal GitHub repo.

The conversion process is almost identical to setting up a generic self-hosted portal, as shown in previous steps in this article. There's one exception in the configuration step. The storage account in the config.design.json file needs to be the same as the storage account of the managed version of the portal. See Tutorial: Use a Linux VM system-assigned identity to access Azure Storage via a SAS credential for instructions on how to retrieve the SAS URL.

Related content

• Learn about Alternative approaches to self-hosting