Skip to content

Deployment

Jump to bottom
Herb Caudill edited this page Sep 25, 2024 · 1 revision

XDev (v2) is currently being hosted as two separate applications, a sync server and the client app, as described below.

XDev Client App

This is hosted as an Azure Static Web App.

Repo: https://github.com/DevResults/xdev
Domain: https://xdev.devresults.com (Still pointing to v1 app but will be replaced soon)
Azure App Service Domain: https://wonderful-water-0b2eba80f.5.azurestaticapps.net
Azure resource: devresults-xdev-client

Provisioning the Static Web App

Creating a new Static Web App using the Azure CLI
Tutorial: https://learn.microsoft.com/en-us/azure/static-web-apps/get-started-cli
CLI Docs: https://learn.microsoft.com/en-us/cli/azure/staticwebapp?view=azure-cli-latest

  1. Create the Static Web App ([cli docs az staticwebapp create -n devresults-xdev-client -g XDev -l EastUs2 --sku Standard
  2. Reset the deployment key az staticwebapp secrets reset-api-key --name devresults-xdev-client
  3. Get the deployment key az staticwebapp secrets list --name devresults-xdev-client
  4. Copy the deployment key's apiKey into an Actions secret called AZURE_STATIC_WEB_APPS_API_TOKEN in the Github repository settings
  5. Create and configure a Github Action workflow file to manage the deployment of the app
    See the "XDev Configuration and Deployment" section below for configuration details

XDev Configuration and Deployment

Configuring the Static Web App
Configuration of the Static Web App is managed by a staticwebapp.config.json file that should be in the root of the deployed app. Ours lives in the public directory of the xdev application so it will automatically be deployed with the root of the application by vite.
Docs: https://learn.microsoft.com/en-us/azure/static-web-apps/configuration

Build configuration (via Github Actions)
Configured via a Github workflow file in the xdev repository
References:

Preview Deployments
The Static Web App deployment workflow is configured to build a preview environment for each pull request opened against the main branch. This allows us to easily view the changes to the app. The Azure integration will add a comment in each PR with a link to the preview environment. Each preview environment will be automatically removed when the associated pull request is closed. Since we're on the Standard tier of Static Web Apps we can have up to 10 preview environments, the limit for the Free tier is 3 environments.
Note: All preview environments are publicly accessible!
References:

Troubleshooting Static Web App Deployments
After initially setting up the Static Web App with modifications to the workflow file in a branch called deploy-to-swa the deployment integration was broken when that branch was merged and deleted. I tried the following things to get things reconnected.

  1. Disconnect the Static Web App using the Azure CLI
    az staticwebapp disconnect -n devresults-xdev-client
  2. Try to reconnect the Static Web App using the Azure CLI
    az staticwebapp reconnect -n devresults-xdev-client --source DevResults/xdev -b main --login-with-github
    This ended up returning an error that the app already existed
  3. Try updating the Static Web App using the Azure CLI
    az staticwebapp update -n devresults-xdev-client --source DevResults/xdev -b main
  4. Reset the deployment API key and update the secret in Github
    I did this manually in the Azure portal and updated the secret in Github
  5. Updated the workflow file to explicitly list the main branch instead of $default-branch
    I had assumed that this was a known thing for Github because it came from the workflow starter file but perhaps it was just meant to be a placeholder you have to change

XDev Sync Server

This is hosted as an Azure App Service.

Repo: https://github.com/DevResults/xdev-syncserver
Domain: https://sync.xdev.devresults.com
Azure App Service Domain: https://devresults-xdev-syncserver.azurewebsites.net
Azure resource: devresults-xdev-syncserver

Provisioning the Azure App Service

Provisioning the App Service in Azure and configuring deployments using Azure WebApp Github Action.

  1. Create a new App Service in an existing Resource Group and App Service Plan
    az webapp create --name devresults-xdev-syncserver --resource-group XDev --plan devresults-xdev --runtime NODE:18LTS
  2. Turn on WebSockets in App Service Configuration page
  3. Download a Publishing Profile for the App Service (Deployment Center -> Manage publishing profile -> Download publish profile) and copy the contents of the file into a repository secret called AZURE_WEBAPP_PUBLISH_PROFILE in Github
  4. Configure the workflow file (deploy.yml) as needed, inspired by this template for Node
  5. Add custom domain to the App Service (Docs)

Other reference docs:

There is also some additional context in the PR that originally hooked things up for v1, which the current version of the deployment workflow is based upon.

Notes about initial trial and error

Deployed app didn't run

Running the app on a Windows-based Azure App Service requires an extra wrapper to properly execute an node "module" app. This is why run.cjs exists, to bootstrap the app. The web.config file also has some configuration about run.cjs. This StackOverflow answer has some details: https://stackoverflow.com/questions/65703421/azure-app-service-nodejs-es-module-error/67111490#67111490

Deployed app didn't have much of anything in node_modules

I added the --shamefully-hoist flag to the pnpm install command to use a flattened modules directory (ref: https://github.com/pnpm/pnpm/issues/6259). This gets us all of the dependencies in the same place so they can be deployed. It should be noted that the pnpm documentation suggests "This is highly discouraged" but that may not apply to this situation.

  • An alternative may be to add the appropriate dependencies for @localfirst/auth-syncserver to this project.
  • Another alternative may be to use the hoisted option for node-linker in the pnpm configuration.

Disable SCM build during deployment?

We might be able to speed up the deployments by not having Kudu try to run a build step on the App Service when the files arrive. This would entail setting SCM_DO_BUILD_DURING_DEPLOYMENT="0". I've seen some documentation that this is automatically skipped for Zip Deployments though so maybe we're all set.

  • Confirmed that zipDeploy does disable the build step on Kudu: ref

See about removing the "unzip" step of the deployment job?

Can we remove this (by passing ./release.zip to the webapps-deploy step?) or even consolidate down to a single "build-and-deploy" job that avoids uploading and downloading an artifact?

  • Confirmed that we can reference ./release.zip to ship a pre-packaged zip file. However, as noted below in "Run from Package disabled" we still need the deployment to unpack the zip file which adds time to the deployment.

Run from Package disabled

I originally thought we could try running the App Service from a deployed zip file, which seems to deploy very quickly. This didn't turn out to work for the sync server because we need to be able to create the .xdev-sync-server-data directory when the server starts. This doesn't seem to work when running from the package so I've disabled it again by setting the value to "0". Here's the original instructions for reference if we want to try to go back.

  • Enable Run from Package for the App Service:
    az webapp config appsettings set --resource-group XDev --name devresults-xdev-syncserver --settings WEBSITE_RUN_FROM_PACKAGE="1"

Clone this wiki locally