# Deploying your website \blurb{Set it up once then don't think about it.} \lineskip \toc \lineskip Deploying the website is trivial on Gitlab and services like Netlify. On GitHub there are a few extra steps **especially if you want a user/org website**. ## Deploying on GitHub **Warning**: the setup to synchronise your local folder and the remote repository is _different_ based on whether you want a user/org website: @@tlist * a _user_ website has a base URL looking like `username.github.io`. * a _project_ website has a base URL looking like `username.github.io/project/`. @@ Make sure to follow the appropriate instructions! ### Creating a repo on GitHub Start by creating an empty GitHub repository @@tlist * for a personal (or org) website the repository **must** be named `username.github.io` (or `orgname.github.io`) see also [the github pages docs](https://pages.github.com/), * for a project website the repo can be named anything you want, let's say `myWebsite`. @@ ### Adding access tokens In order for the deployment action to work on GitHub, you need to set up an access token on GitHub. The steps are explained below but you [can read more on the topic here](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). **STEP 1**: @@tlist * Make a public/private key pair on your local machine with `ssh-keygen -N "" -f franklin` ([see also here](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) for more information about generating ssh keys). * This creates 2 files, the private key: `franklin`, and the public key `franklin.pub`. @@ **STEP 2**: @@tlist * Go to the repository and select *Settings > Secrets* then click on **Add new secret**, * Name the secret `FRANKLIN_PRIV` and copy the contents of the **private key** (`franklin`) from the previous step. @@  **STEP 3**: @@tlist * Go to the repository and select *Settings > Deploy keys* then click on **Add deploy key**, * Name the deploy key `FRANKLIN_PUB` and copy the contents of the **public key** (`franklin.pub`) from step 1. * Give the key write access. @@  **STEP 4**: Remove both files (`franklin`, `franklin.pub`) from your local folder. ### Synchronise your local folder [User/Org website] > This assumes that you're working on a user folder with base URL looking like `username.github.io`. See [this example](https://github.com/tlienart2/tlienart2.github.io) for instance. You need to synchronise your repository and your local website folder; to do so, go to your terminal, `cd` to the website folder and follow the steps below: @@tlist - `git init && git remote add origin URL_TO_YOUR_REPO` - `git checkout -b dev` - `git add -A && git commit -am "initial files"` @@ It is **crucial** to change the branch to `dev` (or any other name that you like that is not `master`). This is because a user/org site **must** be deployed from the `master` branch on GitHub. Now, in an editor, open the file [`.github/workflows/deploy.yml`](https://github.com/tlienart2/tlienart2.github.io/blob/dev/.github/workflows/deploy.yml) and change the `on` section to ```yaml on: push: branches: - dev ``` change also the `BRANCH` line at the end to `BRANCH: master`: ```yaml BRANCH: master FOLDER: __site ``` With all this, if you push changes to `dev` with ``` git push -u origin dev ``` the GitHub action will be triggered and deploy the content of the `__site` folder to the `master` branch. GitHub pages will then deploy the website from the master branch. \note{It takes a couple of minutes for the whole process to complete and your site to be available online.} \note{It is recommended to change your default branch on the repository to `dev` (GitHub may have done that automatically for you). To do this, click on *Settings > Branches* and select the default branch.} ### Synchronise your local folder [Project website] > This assumes that you're working on a user folder with base URL looking like `username.github.io/myWebsite`. See [this example](https://github.com/tlienart2/myWebsite) for instance. Now you need to synchronise your repository and your local website folder; to do so, go to your terminal, `cd` to the website folder and follow the steps below: @@tlist - `git init && git remote add origin URL_TO_YOUR_REPO` - `git add -A && git commit -am "initial files"` @@ That's it! when you push your updates to the `master` branch, the [GitHub action](https://github.com/tlienart2/myWebsite/blob/master/.github/workflows/deploy.yml) will deploy the `__site` folder to a `gh-pages` branch that GitHub Pages will then use to deploy your website. \note{It takes a couple of minutes for the whole process to complete and your site to be available online.} ### Troubleshooting @@tlist - Make sure you have set the access tokens properly, - Make sure GitHub Pages is pointing at the right branch (see screenshot below), - Open an issue on Franklin's GitHub or ask on the **#franklin** juliaslack channel. @@  ## Deploying on GitLab ### Creating a repo on GitLab Start by creating an empty GitLab repository @@tlist * for a personal website the repository **must** be named `username.gitlab.io` see also [the gitlab pages docs](https://about.gitlab.com/stages-devops-lifecycle/pages/), * for a project website the repo can be named anything you want. @@ ### Synchronise your local folder Now you need to synchronise your repository and your local website folder; to do so, go to your terminal, `cd` to the website folder and follow the steps below: @@tlist - `git init && git remote add origin URL_TO_YOUR_REPO` - `git add -A && git commit -am "initial files"` @@ That's it! when you push your updates to the `master` branch, the GitLab CI will copy the `__site` folder to a virtual `public` folder and deploy its content. \note{It takes a couple of minutes for the whole process to complete and your site to be available online.} ## Deploying on Netlify Synchronise your local website folder with a repository (e.g. a GitHub or GitLab repository) then select that repository on Netlify and indicate you want to deploy the `__site` folder. That's it!