Tutorial

Note

Do you find any of these instructions confusing? Edit this file and submit a pull request with your improvements!

To start with, you will need a GitHub account. Create these before you get started on this tutorial. If you are new to Git and GitHub, you should probably spend a few minutes on some of the tutorials at the top of the page at GitHub Help.

📦 Step 2: Generate Your Package

Now it’s time to generate your project.

Use cookiecutter, pointing it at the cookiecutter-webgl repo:

$ cookiecutter https://github.com/romnnn/cookiecutter-webgl.git

You’ll be asked to enter a bunch of values to set the package up. If you don’t know what to enter, stick with the defaults.

🐙 Step 3: Create a GitHub Repo

Go to your GitHub account and create a new repo named myproject, where myproject matches the [project_slug] from your answers to running cookiecutter. This is so that Travis CI can find it when we get to Step 4.

You will find one folder named after the [project_slug]. Move into this folder, and then setup git to use your GitHub repo and upload the code:

$ cd myproject
$ git init .
$ git add .
$ git commit -m "Initial commit."
$ git remote add origin git@github.com:myusername/myproject.git
$ git push -u origin master

Where myusername and myproject are adjusted for your username and project.

You can use HTTPS to push the repository, but it’s more convenient to use a ssh key to push the repo. You can generate a key or add an existing one.

👷 Step 4: Set up TravisCI

Travis-CI * is a continuous integration tool used to prevent integration problems. Every commit to the master branch will trigger automated builds of the application.

Add the repository to your Travis-CI account by activating it. If you have connected travis with GitHub this is done automatically.

*

For private projects go to travis-ci.com, for public ones go to travis-ci.org has been a thing. But afaik all projects should use travis-ci.com as of now.

📝 Step 5: Set up GitHub Pages

GitHub Pages is a service offered by GitHub that will host a static website along with your project’s code for free. Per default, GitHub Pages uses jekyll for templating, but you can use any other tool as long as it generates static html (like yarn build). Once enabled in GitHub’s repository settings, it works by hosting any static assets (using index.html as an entrypoint) in a branch named gh-pages. When using static html from another tool, GitHub requires a file named .nojekyll in the branches root so jekyll won’t be used.

If you do not want to deploy to GitHub Pages, remove the deploy pages build stage from .travis.yml.

If you wish to deploy to GitHub Pages, generate a GitHub access token for public_repo and set this token in your travis build settings at https://travis-ci.com/myusername/myproject/settings as a secret environment variable GH_TOKEN. This will allow travis to access the secret token as $GH_TOKEN to be able to commit and push to the gh-pages branch. The website will be available at https://myusername.github.io/myproject/.

The default deploy pages stage in your templated project’s .travis.yml will already publish your WebGL experiment to Pages, but you might deploy a different website for your project.

🚨 Having problems?

If you experience problems you cannot fix by yourself, create an issue. Be sure to give as much information as possible.