The guide is updated to fit the current Wercker interface and configurations.
Wercker changed its interface and default infrastructure (Docker).
|
@ -1,5 +1,7 @@
|
|||
---
|
||||
author: "Arjen Schwarz"
|
||||
authors:
|
||||
- Arjen Schwarz
|
||||
- Samuel Debruyn
|
||||
date: 2015-01-12
|
||||
linktitle: Automated deployments
|
||||
toc: true
|
||||
|
@ -14,7 +16,7 @@ weight: 10
|
|||
|
||||
# Automated deployments with Wercker
|
||||
|
||||
In this tutorial we will set up a basic Hugo project and then configure a free tool called Wercker to automatically deploy the generated site any time we add an article. We will deploy it to GitHub pages as that is easiest to set up, but you will see that we can use anything. This tutorial takes you through every step of the process, complete with screenshots, and is fairly long.
|
||||
In this tutorial we will set up a basic Hugo project and then configure a free tool called Wercker to automatically deploy the generated site any time we add an article. We will deploy it to GitHub pages as that is easiest to set up, but you will see that we can use anything. This tutorial takes you through every step of the process, complete with screenshots and is fairly long.
|
||||
|
||||
The assumptions made for this tutorial are that you know how to use git for version control, and have a GitHub account. In case you are unfamiliar with these, in their [help section](https://help.github.com/articles/set-up-git/) GitHub has an explanation of how to install and use git and you can easily sign up for a free GitHub account as well.
|
||||
|
||||
|
@ -49,13 +51,19 @@ Let's add a quick **about** page.
|
|||
hugo new about.md
|
||||
```
|
||||
|
||||
Now we'll edit contents/about.md to ensure it's no longer a draft and add some text to it. Once completed it's a good idea to do a quick check if everything is working by running
|
||||
Now we'll edit contents/about.md to ensure it's no longer a draft and add some text to it.
|
||||
|
||||
```bash
|
||||
hugo undraft content/about.md
|
||||
```
|
||||
|
||||
Once completed it's a good idea to do a quick check if everything is working by running
|
||||
|
||||
```bash
|
||||
hugo server --theme=herring-cove
|
||||
```
|
||||
|
||||
If everything is fine, you should be able to see something similar to the image below when you go to localhost:1313 in your browser.
|
||||
If everything is fine, you should be able to see something similar to the image below when you go to localhost:1414 in your browser.
|
||||
|
||||
![][1]
|
||||
|
||||
|
@ -84,18 +92,17 @@ echo "User-agent: *\nDisallow:" > static/robots.txt
|
|||
After this we can add everything to the repository.
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
git commit -a -m "Initial commit"
|
||||
```
|
||||
|
||||
## Adding the project to GitHub
|
||||
|
||||
First we'll create a new repository. You can do this by clicking on the **+** sign at the top right, or by going to [https://github.com/new](https://github.com/new)
|
||||
First we'll create a new repository. You can do this by clicking on the **+** sign at the top right, or by going to https://github.com/new
|
||||
|
||||
We then choose a name for the project (**hugo-wercker-example**). When clicking on create repository GitHub displays the commands for adding an existing project to the site. The commands shown below are the ones used for this site, if you're following along you will need to use the ones shown by GitHub. Once we've run those commands the project is in GitHub and we can move on to setting up the Wercker configuration.
|
||||
|
||||
```bash
|
||||
git remote add origin git@github.com:ArjenSchwarz/hugo-wercker-example.git
|
||||
git remote add origin git@github.com:YourUsername/hugo-wercker-example.git
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
|
@ -105,11 +112,11 @@ git push -u origin master
|
|||
|
||||
## Welcome to wercker
|
||||
|
||||
Let's start by setting up an account for Wercker. To do so we'll go to http://wercker.com and click on the **register** link at the top-right corner.
|
||||
Let's start by setting up an account for Wercker. To do so we'll go to http://wercker.com and click on the **Sign up** button.
|
||||
|
||||
![][3]
|
||||
|
||||
[3]: /img/tutorials/welcome-to-wercker.png
|
||||
[3]: /img/tutorials/wercker-sign-up.png
|
||||
|
||||
## Register
|
||||
|
||||
|
@ -117,23 +124,23 @@ To make life easier for ourselves, we will then register using GitHub. If you do
|
|||
|
||||
![][4]
|
||||
|
||||
[4]: /img/tutorials/register.png
|
||||
[4]: /img/tutorials/wercker-sign-up-page.png
|
||||
|
||||
## Connect GitHub/Bitbucket
|
||||
|
||||
After you are registered, you will need to link your GitHub and/or Bitbucket account to Wercker. You do this by going to your profile settings, and then "Git connections" If you registered using GitHub it will most likely look like the below. To connect a missing service, simply click on the connect button which will then send you to either GitHub or Bitbucket where you might need to log in and approve their access to your account.
|
||||
After you are registered, you will need to link your GitHub and/or Bitbucket account to Wercker. You do this by going to your profile settings, and then "Git connections" If you registered using GitHub it will most likely look like the image below. To connect a missing service, simply click on the connect button which will then send you to either GitHub or Bitbucket where you might need to log in and approve their access to your account.
|
||||
|
||||
![][5]
|
||||
|
||||
[5]: /img/tutorials/connect-github-bitbucket.png
|
||||
[5]: /img/tutorials/wercker-git-connections.png
|
||||
|
||||
## Add your project
|
||||
|
||||
Now that we've got all the preliminaries out of the way, it's time to set up our application. For this we click on the **+ Add** button next to Apps, and then we'll choose to use GitHub as our provider.
|
||||
Now that we've got all the preliminaries out of the way, it's time to set up our application. For this we click on the **+ Create** button next to Applications, and then we'll choose to use GitHub as our provider.
|
||||
|
||||
![][6]
|
||||
|
||||
[6]: /img/tutorials/add-your-project.png
|
||||
[6]: /img/tutorials/wercker-add-app.png
|
||||
|
||||
## Select a repository
|
||||
|
||||
|
@ -141,58 +148,66 @@ Clicking this will make Wercker show you all the repositories you have on GitHub
|
|||
|
||||
![][7]
|
||||
|
||||
[7]: /img/tutorials/select-a-repository.png
|
||||
[7]: /img/tutorials/wercker-select-repository.png
|
||||
|
||||
## Select the repository owner
|
||||
|
||||
In the next step, Wercker asks you to select the repository owner. Just select your own GitHub account and continue.
|
||||
|
||||
![][8]
|
||||
|
||||
[8]: /img/tutorials/wercker-select-owner.png
|
||||
|
||||
## Configure access
|
||||
|
||||
This step can be slightly tricky. As Wercker doesn't access to check out your private projects by default it will ask you what you want to do. When your project is public, as needs to be the case if you wish to use GitHub Pages, the top choice is recommended. When you use this it will simply check out the code in the same way anybody visiting the project on GitHub can do.
|
||||
|
||||
![][8]
|
||||
![][9]
|
||||
|
||||
[8]: /img/tutorials/configure-access.png
|
||||
[9]: /img/tutorials/wercker-access.png
|
||||
|
||||
## Wercker.yml
|
||||
|
||||
Wercker will now attempt to create an initial wercker.yml file for you. Or rather, it will create the code you can copy into it yourself. Because there is nothing special about our project according to Wercker, we will simply get the `wercker/default` box. So what we do now is create a wercker.yml file in the root of our project that contains the provided configuration, and after we finish setting up the app we will expand this file to make it actually do something.
|
||||
|
||||
![][9]
|
||||
|
||||
[9]: /img/tutorials/werckeryml.png
|
||||
|
||||
## Public or not
|
||||
|
||||
This is a personal choice, you can make an app public so that everyone can see more details about it. This doesn't give you any real benefits either way in general, although as part of the tutorial I have of course made this app public so you can see it in action [yourself](https://app.wercker.com/#applications/54b1e45eda3a4af76406ece6).
|
||||
Wercker will now attempt to create an initial *wercker.yml* file for you. Or rather, it will create the code you can copy into it yourself. Because there is nothing special about our project according to Wercker, we will simply get the `debian` box. So what we do now is create a *wercker.yml* file in the root of our project that contains the provided configuration, and after we finish setting up the app we will expand this file to make it actually do something.
|
||||
|
||||
![][10]
|
||||
|
||||
[10]: /img/tutorials/public-or-not.png
|
||||
[10]: /img/tutorials/werckeryml.png
|
||||
|
||||
## Public or not
|
||||
|
||||
This is a personal choice, you can make an app public so that everyone can see more details about it. This doesn't give you any real benefits either way in general, although as part of the tutorial I have of course made this app public so you can see it in action [yourself](https://app.wercker.com/#applications/5586dcbdaf7de9c51b02b0d5).
|
||||
|
||||
![][11]
|
||||
|
||||
[11]: /img/tutorials/public-or-not.png
|
||||
|
||||
## And we've got an app
|
||||
|
||||
The application is added now, and Wercker will be offering you the chance to trigger a build. As we haven't pushed up the **wercker.yml** file however, we will politely decline this option.
|
||||
|
||||
![][11]
|
||||
![][12]
|
||||
|
||||
[11]: /img/tutorials/and-we-ve-got-an-app.png
|
||||
[12]: /img/tutorials/and-we-ve-got-an-app.png
|
||||
|
||||
## Adding steps
|
||||
|
||||
And now we're going to add the steps themselves. First, we go to the "Steps" action in the sidebar and then search for hugo. The first result is the **Hugo-Build** task, which we select.
|
||||
And now we're going to add the steps themselves. First, we go to the "Registry" action in the top menu and then search for "hugo build". The first result is the **Hugo-Build** task, which we select.
|
||||
|
||||
![][12]
|
||||
![][13]
|
||||
|
||||
[12]: /img/tutorials/adding-steps.png
|
||||
[13]: /img/tutorials/wercker-search.png
|
||||
|
||||
## Using Hugo-Build
|
||||
|
||||
Inside the details of this step you will see how to use it. At the top is a summary for the very basic usage, but when scrolling down you go through the README of the step which will usually contain more details about how to use it including a full example of using the step. So we return to our project, and while making it fit our project better we add these details to our wercker.yml file so it looks like this. Wercker also has a [page](http://devcenter.wercker.com/articles/werckeryml/validate.html) for validating wercker.yml files, and it's usually a good idea to do so before committing changes.
|
||||
|
||||
```yaml
|
||||
box: wercker/default
|
||||
box: debian
|
||||
build:
|
||||
steps:
|
||||
- arjen/hugo-build:
|
||||
version: 0.12
|
||||
version: 0.14
|
||||
theme: herring-cove
|
||||
flags: --buildDrafts=true
|
||||
```
|
||||
|
@ -200,27 +215,26 @@ build:
|
|||
This concludes the first step, so we'll test that it all works as it should by pushing up our wercker.yml file and seeing the magic at work.
|
||||
|
||||
```bash
|
||||
git add wercker.yml
|
||||
git commit -m "Add wercker.yml"
|
||||
git commit -a -m "Add wercker.yml"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
Once completed a nice tick should have appeared in front of your first build, and if you want you can look at the details by clicking on it. However, we're not done yet as we still need to deploy it to GitHub Pages.
|
||||
|
||||
![][13]
|
||||
![][14]
|
||||
|
||||
[13]: /img/tutorials/using-hugo-build.png
|
||||
[14]: /img/tutorials/using-hugo-build.png
|
||||
|
||||
## Adding a GitHub Pages step
|
||||
|
||||
In order to deploy to GitHub Pages we need to add a deploy step. Once again searching through the Steps repository we find that the most popular step is the **lukevevier/gh-pages** step so we add the configuration for that to our wercker.yml file, which then becomes this:
|
||||
|
||||
```yaml
|
||||
box: wercker/default
|
||||
box: debian
|
||||
build:
|
||||
steps:
|
||||
- arjen/hugo-build:
|
||||
version: 0.12
|
||||
version: 0.14
|
||||
theme: herring-cove
|
||||
flags: --buildDrafts=true
|
||||
deploy:
|
||||
|
@ -237,17 +251,17 @@ Secondly we've configured the basedir to **public**, this is the directory that
|
|||
|
||||
And lastly, you can see here that this has a **$GIT_TOKEN** variable. This is used for pushing our changes up to GitHub and we will need to configure this before we can do that. We do this by going to our app's settings and clicking on **Deploy targets**. Now, we **Add deploy target** and select **Custom deploy**.
|
||||
|
||||
![][14]
|
||||
![][15]
|
||||
|
||||
[14]: /img/tutorials/adding-a-github-pages-step.png
|
||||
[15]: /img/tutorials/adding-a-github-pages-step.png
|
||||
|
||||
## Configure the deploy step
|
||||
|
||||
Simply fill in the name, and make sure you enable **auto deploy** from the **master** branch. Next you add a variable for the **GIT_TOKEN**, for this you'll need to create an access token in GitHub. How to do that is described on a [GitHub help page](https://help.github.com/articles/creating-an-access-token-for-command-line-use/). With the deploy step configured in Wercker, we can push the updated wercker.yml file to GitHub and it will create the GitHub pages site for us. The example site we used here is accessible under hugo-wercker.ig.nore.me
|
||||
|
||||
![][15]
|
||||
![][16]
|
||||
|
||||
[15]: /img/tutorials/configure-the-deploy-step.png
|
||||
[16]: /img/tutorials/configure-the-deploy-step.png
|
||||
|
||||
## Conclusion
|
||||
|
||||
|
|
BIN
docs/static/img/tutorials/add-your-project.png
vendored
Before Width: | Height: | Size: 44 KiB |
BIN
docs/static/img/tutorials/adding-steps.png
vendored
Before Width: | Height: | Size: 59 KiB |
BIN
docs/static/img/tutorials/configure-access.png
vendored
Before Width: | Height: | Size: 76 KiB |
Before Width: | Height: | Size: 94 KiB After Width: | Height: | Size: 90 KiB |
Before Width: | Height: | Size: 30 KiB |
BIN
docs/static/img/tutorials/register.png
vendored
Before Width: | Height: | Size: 24 KiB |
BIN
docs/static/img/tutorials/select-a-repository.png
vendored
Before Width: | Height: | Size: 44 KiB |
BIN
docs/static/img/tutorials/welcome-to-wercker.png
vendored
Before Width: | Height: | Size: 33 KiB |
BIN
docs/static/img/tutorials/wercker-access.png
vendored
Normal file
After Width: | Height: | Size: 59 KiB |
BIN
docs/static/img/tutorials/wercker-add-app.png
vendored
Normal file
After Width: | Height: | Size: 46 KiB |
BIN
docs/static/img/tutorials/wercker-git-connections.png
vendored
Normal file
After Width: | Height: | Size: 26 KiB |
BIN
docs/static/img/tutorials/wercker-search.png
vendored
Normal file
After Width: | Height: | Size: 31 KiB |
BIN
docs/static/img/tutorials/wercker-select-owner.png
vendored
Normal file
After Width: | Height: | Size: 19 KiB |
BIN
docs/static/img/tutorials/wercker-select-repository.png
vendored
Normal file
After Width: | Height: | Size: 30 KiB |
BIN
docs/static/img/tutorials/wercker-sign-up-page.png
vendored
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
docs/static/img/tutorials/wercker-sign-up.png
vendored
Normal file
After Width: | Height: | Size: 56 KiB |
BIN
docs/static/img/tutorials/werckeryml.png
vendored
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 51 KiB |