Free Hosting of Web Applications using Angular and GitHub Pages

If you’ve been a Research Software Engineer for a while, then this story will probably feel very familiar:

An academic wants a website, but they aren’t sure exactly what they want and they aren’t particularly tech-savvy — which is why they hired you, after all! You’ve got a vague idea of what you think they are asking for, but that might not be what they actually want. So, you decide to throw together a quick prototype so that they can see what you have in mind and you can work together to iterate towards a final solution.

It’s a common scenario and one that our team encounters regularly. But is there a way to quickly develop and host a web app with minimal time/effort (that doesn’t cost too much)?

Well, yes. There are, of course, several ways you could do it, but I wanted to discuss one particular technique that I’ve been using, which uses Angular and GitHub Pages. Specifically, I’m talking about taking an existing project and configuring it to work with GitHub pages, something that I only managed to do after cobbling together the following solution from a number of other tutorials and forum posts.

First, some quick background information.

Angular

Angular is a framework that automates the creation of the various “components” that make up the application, allows for modular designs that can be easily changed and includes tools to help you test your application locally. There are plenty of resources on how to get started with Angular elsewhere, including this guide and this tutorial.

GitHub Pages

Part of the GitHub platform, GitHub Pages allows you to host your application from within your GitHub repository, including automatic deployment when you push a new version to the repo (and it’s free!).

Setting It Up

So, I’m assuming you’ve already got an Angular application set up in a GitHub repo - maybe you’ve been running it locally to show to your client in person (or over Zoom!) - but now you want to host it somewhere, perhaps so your client can interact with it and give you more detailed feedback.

Step 1: Configure GitHub Pages

First, you need to enable GitHub Pages for your repository. To do this, go to your GitHub repo and then go to Settings → Pages. You should see an option that looks like this:

You can then select which branch you want to use, perhaps a specific deployment/production branch (I just used “main” for this example). You then need to select where the files for your app are stored and, for some reason, you can only select “(root)” or “/docs”. I decided to use “/docs”.

Step 2: Building Your Application

The next thing you need to do is to run Angular’s build service to generate the code for your site and put the generated code into the “docs” folder in your repo. To do this, we need to change the Angular config.

Open “angular.json” (in the root of your project) and change the “outputPath” to “docs”, as shown in the screenshot below.

Now, when you build the project using:

ng build --prod ⠀⠀⠀⠀⠀⠀// “prod” = “production”

… the compiled files should go into the ‘docs’ folder. Then, when you check those files in to GitHub, the application will automatically be deployed and you will see the following message on the Settings → Pages section of your repo to say that it has worked successfully:

NOTE: It will say “Your site is ready to be published…” while it is being processed (meaning that it hasn’t actually deployed yet), but this shouldn’t take long.

Step 3: Fix Routing Errors

However, if you try and visit your site (using the URL that GitHub gives you — see above), you may get errors because the browser cannot locate the relevant (i.e. CSS/JavaScript) files. To fix this, we need to make sure Angular knows where the files are being hosted on GitHub pages.

NOTE — There may be a better way to do this (i.e. by editing a config file in your Angular project), but this is the only solution that seems to work.

You can specify an “baseHref” parameter to the Angular build command, as shown below:

ng build --prod --baseHref=/my-app-url/

Where “my-app-url” is the additional text on the end of the URL provided by GitHub (“turing-diabetes-classification” in the example above).

Once the application has been rebuilt, check the generated files into GitHub and, once deployed, the application should new know where to look for your site’s files and everything should work.

Bonus Tip: Custom 404

It is worth noting that Angular’s routing mechanism behaves differently in production mode than it does when running locally. If you try to go directly to [my-app-url]/welcome, for example, it might not work and you’ll see a 404 page. One way round this is to create a custom 404 Page and set it to redirect to a valid address. A full description of how to do this can be found here.

NOTE: Remember to put the file for your 404 page in the “docs” folder.

In our case, the 404.html file contains the following code to redirect to the root of the site, which then correctly loads the site’s “welcome” page:

<head>
<meta http-equiv=”refresh” content=”0; URL=’https://newcastlerse.github.io/turing-diabetes-classification/'" />
</head>

NOTE: Make sure the 404 page doesn’t get deleted when you rebuild the project. Personally, I use GitHub Desktop and “revert” the changes if the file has been removed.

Final Thoughts

And there you have it, a simple way to host an Angular web application for free using GitHub pages. You don’t necessarily get the most user-friendly URL, but the hosting is free and it gives you somewhere to collaborate on your project with your PI/client. You can even give them access to the repository so they can add issues and so on.

Anyway, I hope you found this helpful. Thanks for Reading.

Check out the Newcastle RSE Team blog for more posts on a whole range of interesting software-related topics.