How to run your ECE 391 OS on GitHub Pages

391OS-Deploy.md

Running your ECE 391 OS on GitHub Pages

This is a guide on how to run your ECE 391 OS via the browser. We will use the v86 library to do so. This guide assumes that your source code is on a private* GitHub repository.

* Please do not put your source code in a public repository. This can lead to academic integrity violations (for both visitors to your repository AND YOU)

Test that your OS will work with v86

You can use the v86 demo page to see what your OS will look like in the browser and test its compatibility with v86. Simply upload your mp3.img file (outputted by make) as the Hard Disk Drive and hit "Start Emulation".

To use the exact page and layout as the above page, you'll want to make v86 yourself (you can follow their instructions to do so). Another option is to copy the built files from the template below.

Create your HTML template

This guide will use a much more basic layout than the demo page above. You can see my HTML template (and get the required v86 JS files) here. When changing anything related to the v86 emulator itself, please make sure that you're following the v86 documentation. Their documentation isn't great at the moment, so I wouldn't recommend messing with it too much. If you implemented more advanced extra credit options, however, you may have to get into the weeds to enable them.

Modify the styling and markup of my HTML template to your liking. You'll need to run it as a web server to test (you can do so via python -m http.server and many other ways as well).

Create a new public repository

GitHub pages on private repositories is a Pro (read: paid) feature currently. To get around this we can make a public repository for the express purpose of hosting a GitHub pages site. For example, my source repository is called 391OS, so I created a new public repository called 391OS-Public for this project.

To set up GitHub pages for this public repository go to Settings > Pages and set the "source" dropdown to point to the main branch. This will publish the site at https://<your GH org or username>.github.io/<your repo name>

Create a PAT

To automate the process we'll need a GitHub personal access token. To create one, go to your GitHub Settings > Developer Settings > Personal Access Tokens and create a new token. Give this token the public_repo permission only (you will need to be able to push to this repo and nothing else).

Copy the PAT and save it in your private repository's secrets. Do this by going to your private repository > Settings > Secrets and create a New Repository Secret. Name it GH_PAT and paste in the value from the earlier step.

Create your GitHub Action

Now (still in your private repository) we'll create a GitHub Action to automatically push the mp3.img from the private repository to the public repository whenever it is updated.

This assumes that you run the typical build steps and commit mp3.img to your private repository on each update. I haven't yet written a GitHub Action to do the build step automatically, though I do think it's possible.

Go to the Actions tab and click "set up a workflow yourself" (if you have other workflows, click "New workflow" first). We'll now edit that .yaml file to describe our action (you can change its name to whatever you like). Below is my GitHub Action yaml which you can copy, but will need to change to fit your repository and secret names.

# This workflow deploys changes to the public-facing repository's GitHub Pages
# We use a separate repository because GitHub Pages on private repositories is not free

name: deploy

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the master branch
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # The "build" workflow will move all required files into the target repository
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out this repository (source) under source
      - uses: actions/checkout@v2
        with:
          path: source
      
      # Check out the target repository under deployment
      # Token required because it is a different repository
      - uses: actions/checkout@v2
        with:
          repository: <your GH org or username>/<public repo name>
          token: ${{ secrets.GH_PAT }}
          path: target

      # Move mp3.img to public repo
      # Edit this to move mp3.img to a location of your liking!
      - name: Move mp3.img to target
        run: |
          cp source/student-distrib/mp3.img target/mp3.img
          cd target
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add mp3.img
          git commit -m "Updating mp3.img from private source repo"
          git push

When you commit this action it will put it in a .github folder in your repository. It will also automatically run (since it runs on pushes to main and that is what you just did). Check to see that it succeeds (in the actions tab you should see a green check after a bit. If you get a red X instead, check the logs to see what went wrong).

Now whenever you push to main this GitHub Action will automatically update mp3.img within your public repository. You can edit the public repository to make the webpage as nice as you wish! Additionally none of your source code will be exposed publicly, only the mp3.img file will be.

Issues

If you have any issues following this guide, let me know in the comments and I'll see if I can help :)