iTwin Viewer — Deployed

By Carl Hinkle and Arun George

Ready to release!

So you’ve written an amazing iTwin powered application and you have it running flawlessly on your local computer! The next step is to deploy it on the internet so that all of your users can access it. Fortunately, this is a very simple thing to do with the iTwin Viewer.

When the npm run build command is run, the output is a static website. This means that all of the files and assets that are needed to serve your site to your users are bundled under the same parent directory, and all that you need to do is get that directory to a host that can serve them. Below, I’ll show you how to use two different popular hosting services to deploy an iTwin Viewer based application.

Jump to Netlify

Jump to Heroku

Even though I’m picking two providers, the general concepts that I’ll show will apply to any hosting situation.+6

Things to watch out for

There are a couple of things to watch out for when you’re getting ready to host your application.

1. You need to get the values from your .env file into the provider’s environment.
2. You need to update your OIDC client with the proper redirects.

Once you have those two items checked off, the rest is simple. Just follow your hosting provider’s instructions for hosting a React-based application.

Prereqs

Before we jump into the deployment process, let’s check off a few boxes.

• An iTwin Viewer based application. If you need something to work with, check out the getting started guide, then come back here. It won’t take long, I promise.
• Your code pushed to GitHub. It doesn’t matter if you have a public or private repo, but you need your code in GitHub in order to really unleash the power of modern hosting providers.

I guess that’s only two boxes. Not bad!

Now, without further ado, let’s dive into our first hosting platform, Netlify.

Deploying to Netlify

We’re going to start with Netlify. Why? It’s slightly easier to get going because it’s designed from the ground up to serve static sites. To follow along you’ll need to sign up for a free account. This will give you more than enough bandwidth and build minutes to keep your site deployed 24/7/365.

Create a new site

After you log in to your new account, you’ll be on your “Team overview” page. Click on “New site from Git”

Next, click on GitHub to connect to your repository

Next, click on the repository where your code is hosted. You might need to click on the “Configure the Netlify app on GitHub” link first.

Then, choose the branch you want to deploy (it’ll probably be main, which is already selected), and change the Publish directory to build/.

Next, click on Show Advanced build settings and add each of the variables in your .env file to a New variable. Note that at this point you still won’t have your redirects set up correctly. But that’s ok, we’ll fix it in a few minutes.

NOTE: The IMJS_CONTEXT_ID and IMJS_IMODEL_ID variables are optional. If you don't provide them, you can pass the values in a query string as https://my-custom-domain.netlify.app?iModelId=<value>&contextId=<value>

Now click Deploy Site, go grab a coffee, and wait a few minutes for the deployment to finish. If you don’t see any errors in the log, congrats, you’re deployed!

Almost…the only thing left to do is set up your OIDC redirects.

Your OIDC Redirects

During development, your redirects were set up to point to http://localhost, which is exactly what you want. But now that you’re out in the Wild West World of the Internet you need to be a little more restrictive. You’ll need to update your OIDC client with your site’s actual URL.

Before we hop over to the OIDC configuration, copy the full URL of your new site, including the https://

Next — in a new browser tab open My Apps | iTwin Platform and click on your client. Then scroll down to the redirects section and click the + button. Your site's redirect URL should point to origin + /signin-callback, and post logout redirect can point back to origin.

Click on Save. It’ll take 15–20 minutes for the change to make it through the system…so while we’re waiting let’s go back to Netlify.

Update the Netlify configuration

We’re almost done!

The penultimate thing that we need to do is update the Netlify environment variables to match the URL in the OIDC client, then redeploy.

On your Site Overview page, click on Site settings

On the Build and Deploy panel, scroll down to the Environment section and click on Edit variables

Enter your site’s URL, again including the scheme so that it exactly matches what you entered in the OIDC configuration. Then, click Save.

Finally — we’ll need to jump back to our git repo and add a way to manage the redirects we just added. Add a new file to the root of your repo called netlify.toml (you can read more about all the things you can do with this file here) and copy the following content below.

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Once added, commit your changes and push that up to GitHub. This should automatically trigger a new deployment.

If all goes well, (once the deployment is finished and your change to the OIDC client has worked its way through the system), you should be able to click on the link in your Deploys dashboard and open your viewer!

Netlify Summary

So, what have we done?

Starting with nothing more than a GitHub repo, in less than 15 minutes (not counting the time to build or for the OIDC changes to propagate) you have an iTwin Viewer based site live on the internet, for free!

And as an added bonus…we set up continuous deployment! Any time that you make a change to the main branch (or whichever branch you chose for deployments), a brand new build will go live so your site never goes out of date.

That’s it for Netlify, next up let’s take a look at Heroku.​

Deploying to Heroku

To follow along you’ll need to sign up for a free account. This will give you more than enough bandwidth and build minutes to keep your site deployed 24/7/365.

Create a new app

After you log in to your new account, you’ll be on an empty dashboard page for all your app. Let’s fix that. Click on the “New” dropdown and select “Create new app”.

Create a new app and enter its name. This name will be the subdomain where your app is deployed. For example, if you named your app my-itwin-viewer, the app will be deployed to https://my-itwin-viewer.herokuapp.com, and we'll use this when configuring our OIDC client redirects. Note, the app name will have to be unique and unused by anyone else. You can also update the region where your site is deployed to for a faster connection. Once you're done click on "Create App" and you're almost there!

Now you’ll be redirected to the “Deploy” tab where you’ll set up your repository connection.

Select GitHub to be your deployment method, connect to your Github account and grant access to your repositories. Search for the repository you want to use for deployments and connect to it.

Your OIDC Redirects

Now let’s go back to our iTwin App’s registration page on My Apps | iTwin Platform and add redirects for our app. As mentioned earlier we already know where our app will be deployed, so go back and copy the URL if you need to. Add both a Redirect and Post logout redirect for your app, with the base URL matching where our app will be deployed.

Once ready hit “Save”. Note that it can take 10 minutes or so for these changes to take effect.

Heroku App Settings

Now that we have our OIDC client configured, we can update our Heroku App to reflect this. Then you’ll have a functional deployment!

Let’s go back to our Heroku app dashboard and navigate to the “Settings” tab. Scroll down to the “Config Vars” section, and then click on “Reveal Config Vars”.

Add all the environment variables from your .env file, and update the variables for the redirect URIs to match what you just configured.

NOTE: The IMJS_CONTEXT_ID and IMJS_IMODEL_ID variables are optional. If you don't provide them, you can pass the values in a query string as https://my-itwin-viewer.herokuapp.com?iModelId=<value>&contextId=<value>

Now scroll down to the “Buildpacks” section, and click on “Add Buildpack”. These are basically scripts we’ll need to run to make sure our SPA works as expected. This lets Heroku know how to run a build of your viewer and serve the static files from the build output directory, as well as manage routing. Copy and paste the buildpack URL for the Create React App Buildpack and then click on "Save Changes".

Deployment

Now we’re pretty much ready to deploy our app. Let’s navigate back to the “Deploy” tab and scroll down to the end of the page.

The first time you release, you need to do it manually. Do so by clicking on the “Deploy Branch” button in the “Manual Deploy” section.

But this is annoying to do every time we make a change to our repo. So let’s setup automatic deployments. Click on the “Enable Automatic Deploy` button in the “Automatic deploys” section.

Now anytime you push a change to your git repo, Heroku will automatically deploy those changes.

Go get some (more) coffee or beer while your app deploys. And by the time you’re back, your app should be deployed.

If you’re able to sign in and view your model…congrats! You have a fully functional deployed iTwin Viewer.

Deploying without Routing Rules

To deploy to a generic webserver where you don’t have access to server-side routing rules, you can create the signin-callback page in your code that will set the user store and redirect back to origin. In the iTwin Viewer source, create a directory called “signin-callback” with a file named “index.html” in the “public” directory containing the following:

<html>
<head>Redirect</head>
 <script type=”text/javascript” src=”https://cdnjs.cloudflare.com/ajax/libs/oidc-client/1.9.1/oidc-client.min.js">
 <script>
 Oidc.Log.logger = console;
 Oidc.Log.level = Oidc.Log.DEBUG;
var userManager = new Oidc.UserManager({
 authority: “https://ims.bentley.com",
 client_id: “”,
 response_type: “code”,
 redirect_uri: location.origin + “/signin-callback”,
 scope: “openid email profile organization itwinjs”,
 userStore: new Oidc.WebStorageStateStore({ store: window.localStorage })
 });
if (window.parent && window !== window.parent) {
 userManager.signinSilentCallback();
 } else {
 userManager.signinRedirectCallback()
 .then(function (user) {
 window.location.replace(location.origin)
 });
 }
 </script>
<body>
</body>
</html>

You’ll need to fill out your client_id, redirect_uri if different from the origin, and the appropriate scopes.
On build, the signin-callback page should exist that will handle the sign-in callback redirect.

What now?

The iTwin world is your oyster, go out and build some amazing products!

• Learn more about iTwin Platform development
• Learn about the iTwin.js SDK
• Check us out on GitHub
• Ask a question on GitHub Discussions or use the #bentley-itwin tag on Stack Overflow