Objective:
This doc will help you have a better understanding of the self-hosted portal architecture, and the binding behind the scene.
In some cases you might need functionality beyond the customization and styling options supported in the managed developer portal. If you need to implement custom logic, which isn't supported out-of-the-box, you can modify the portal's codebase, available on GitHub . For example, you could create a new widget to integrate with a third-party support system.
How to build and publish a self-hosted developer:
Please go over the following document to build and publish a self-hosted developer portal, we will not expand the section in this article.
- https://github.com/Azure/api-managemez`nt-developer-portal/wiki/Self-hosting-the-portal
- https://github.com/Azure/api-management-developer-portal/wiki/Alternative-processes-for-self-hosted-...
Stage architecture:
We will introduce the architectures and bindings in 4 stages during self-hosted portal development:
- Local Debug
- Publish Project Locally
- Publish your static files to storage account by Az command or any tools you prefer
- Visit the static website
1. Local Debug
Git bash into your repository, start local debug by command “npm start”:
- Local Browser will requesting data from management endpoint
- All the file content, text and reference to media files stored in storage are fetched from management endpoint
- The web page is dynamically built and displayed to end users
2. Publish project locally
After modified the code and widget, call “npm run publish”
- The publishing worker will get the portal code like custom widgets and custom code
- Then get all file content, text and reference to media files stored in storage from management endpoint
- Built them into static files
3. Publish your static files to storage account by Az command or any tools you prefer
This step is straight forward. Simply copy the file generated from local to Storage Account by running az command.
az storage blob upload-batch --source dist/website --destination '$web' --connection-string <account-connection-string>
4. When visiting the static website.
- All the content and images are file static files
- However, we still need dynamic data inject into these static files like API list, API spec, products…
(Optional) Use Custom Storage Account
We can achieve high flexibility and more control by using custom storage account. If you add the storage information in the config.design.json the media changes will be stored in your own storage account instead of the APIM managed one. Similarly, if you add use the same storage account in config.publish.json, the publishing worker will try to pull the data stored from there.
You can get even more control by specifying a different storage account from config.design.json and config.publish.json. But please be careful when handling the branch changes.
Go to the src folder and open the config.design.json file. Besides all the settings mentioned in the official document, you can specify your storage account container and access method by configuring the file:
{
...
"blobStorageContainer": "<design container name>",
"blobStorageUrl":”<storage SAS>”,
}
To generate the storage SAS (Shared access ), you can refer to the document from Azure storage. Multiple ways can be used to generate the service SAS token. I will share the way to generate from Azure Portal.
- Go to Azure Portal, select the storage account.
- Go to Shared Access signature under Security + Networking.
- Please sure you change the expiry date to desired date. The default expiration date will be very short.
- Other properties, you can follow the screenshot shared below.
- Click Generate SAS and connection string
- Replace <storage SAS> in the config.desgin.json file with the Blob service SAS URL from last step.
Recommendations
Please backup data.json file in script.v3 folder regularly by executing capture.bat from the self-hosted project in our GitHub
- If they don't backup data.json file, they will end up losing everything if
- There is a bug which may clear up all the developer portal content in our DB
- Someone from customer company may mistakenly reset the content
- Customer can run generate.bat command to restore the backup data.json
- If customer run generate.bat command with default data.json, then their developer portal will be reset to default
If you use self-hosted developer portal, you should not use managed developer portal. They will have mixed data between self-host and managed developer portal, and it's very likely to make mistakes
Common Questions and Troubleshooting
1. If you are using custom storage and seeing you uploaded image failed to be loaded in either design or publish stage.
You can open your browser developer tool -> Network trace. Find the record for loading picture. Most common response is 404 and 401.
- If the error message is 404, it is an indication that give blob cannot be found in the blob storage. Please make sure the storage account is correct, and the blob didn’t get accidentally deleted.
- If the error message is 401, it is most likely you are using the wrong or expired SAS token. Please follow the previous section to refresh the SAS token.
2. How to enable AAD sign-in on the self-hosted portal? Should I add a custom widget to the sign-in page?
No, you don’t need to add the custom widget or change the script. Please just follow the instruction to configure the AAD sign-in. This configuration will not require any additional operations for the self-hosted portal. These data will be generated from the API management endpoint, thus the data will be loaded to the browser automatically during the local debug. This also applies to Enable console OAuth support, you don’t need extra configuration.
3. If I go to the local debug and customize the portal, I can see it also affects the managed portal. Is this expected?
It depends. As mentioned in the structure diagram, we can see the local browser will communicate with the management endpoint to load/upload portal data. If you are using the administrator mode to change the configuration in local debug (Ex. Upload a picture and use it as a new layout of the existing widget), the data will be synchronized to the API management portal database and generated a new version. At this time, if you go to your managed portal in administrator mode, you can also the changes made from local debug. However, these changes will not be applied to the published version. If you would like to apply the changes to the managed portal, you need to publish the managed portal again.
On the other hand, self-implemented widgets that are saved in your local files will NOT be synchronized to the API management database. The reason is that these data are stored as local Portal data. After publishing, these will be packed into static files.