mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-17 21:01:26 +02:00
Merge commit 'b9bd35d72e14932fb6588ff62b90cddef0a060fc' as 'docs'
This commit is contained in:
Bjørn Erik Pedersen
20
docs/content/en/hosting-and-deployment/_index.md
Normal file
20
docs/content/en/hosting-and-deployment/_index.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Hosting & Deployment
|
||||
linktitle: Hosting & Deployment Overview
|
||||
description: Site builds, automated deployments, and popular hosting solutions.
|
||||
date: 2016-11-01
|
||||
publishdate: 2016-11-01
|
||||
lastmod: 2016-11-01
|
||||
categories: [hosting and deployment]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 01
|
||||
weight: 01 #rem
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: false
|
||||
---
|
||||
|
||||
Because Hugo renders *static* websites, you can host your new Hugo website virtually anywhere. The following represent only a few of the more popular hosting and automated deployment solutions used by the Hugo community.
|
||||
@@ -0,0 +1,249 @@
|
||||
---
|
||||
title: Host-Agnostic Deploys with Nanobox
|
||||
linktitle: Host-Agnostic Deploys with Nanobox
|
||||
description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more...
|
||||
date: 2017-08-24
|
||||
publishdate: 2017-08-24
|
||||
lastmod: 2017-08-24
|
||||
categories: [hosting and deployment]
|
||||
keywords: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode]
|
||||
authors: [Steve Domino]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 05
|
||||
weight: 05
|
||||
sections_weight: 05
|
||||
draft: false
|
||||
aliases: [/tutorials/deployment-with-nanobox/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
|
||||
|
||||
Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application.
|
||||
|
||||
{{% note %}}
|
||||
If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox)
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
## What You'll Need
|
||||
|
||||
With Nanobox you don't need to worry about having Go or Hugo installed. They'll be installed as part of the development environment created for you.
|
||||
|
||||
To get started you'll just need the following three items:
|
||||
|
||||
* [A Nanobox Account](https://nanobox.io) - Signup is free
|
||||
* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool
|
||||
* An account with a hosting provider such as:
|
||||
- [AWS](https://docs.nanobox.io/providers/hosting-accounts/aws/)
|
||||
- [Google](https://docs.nanobox.io/providers/hosting-accounts/gcp/)
|
||||
- [Azure](https://docs.nanobox.io/providers/hosting-accounts/azure/)
|
||||
- [DigitalOcean](https://docs.nanobox.io/providers/hosting-accounts/digitalocean/)
|
||||
- [Linode](https://docs.nanobox.io/providers/hosting-accounts/linode/)
|
||||
- [More...](https://docs.nanobox.io/providers/hosting-accounts/)
|
||||
- [Roll Your Own](https://docs.nanobox.io/providers/create/)
|
||||
|
||||
### Before You Begin
|
||||
|
||||
There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application.
|
||||
|
||||
#### Connect a Host Account
|
||||
|
||||
Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/).
|
||||
|
||||
#### Launch a New Application on Nanobox
|
||||
|
||||
[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and to select a host and region.
|
||||
|
||||
With those out of the way you're ready to get started!
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
{{% note %}}
|
||||
If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox)
|
||||
{{% /note %}}
|
||||
|
||||
To get started, all you'll need is an empty project directory. Create a directory wherever you want your application to live and `cd` into it:
|
||||
|
||||
`mkdir path/to/project && cd path/to/project`
|
||||
|
||||
### Configure Hugo to run with Nanobox
|
||||
|
||||
Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`:
|
||||
|
||||
{{< code file="boxfile.yml" >}}
|
||||
run.config:
|
||||
|
||||
# use the static engine
|
||||
engine: static
|
||||
engine.config:
|
||||
|
||||
# tell the engine where to serve static assets from
|
||||
rel_dir: public
|
||||
|
||||
# enable file watching for live reload
|
||||
fs_watch: true
|
||||
|
||||
# install hugo
|
||||
extra_steps:
|
||||
- bash ./install.sh
|
||||
|
||||
deploy.config:
|
||||
|
||||
# generate site on deploy
|
||||
extra_steps:
|
||||
- hugo
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
If you already have a functioning Hugo app, after adding the boxfile, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox).
|
||||
{{% /note %}}
|
||||
|
||||
### Installing Hugo
|
||||
|
||||
Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available.
|
||||
|
||||
Do this by adding a custom install script at the root of your project that will install Hugo automatically for you:
|
||||
|
||||
{{< code file="install.sh" >}}
|
||||
|
||||
#!/bin/bash
|
||||
|
||||
if [[ ! -f /data/bin/hugo ]]; then
|
||||
cd /tmp
|
||||
wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz
|
||||
tar -xzf hugo_0.31.1_Linux-64bit.tar.gz
|
||||
mv hugo /data/bin/hugo
|
||||
cd -
|
||||
rm -rf /tmp/*
|
||||
fi
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh`
|
||||
{{% /note %}}
|
||||
{{% note %}}
|
||||
Make sure to check the version of Hugo you have installed and update the install script to match.
|
||||
{{% /note %}}
|
||||
|
||||
### Generating a New Hugo App
|
||||
|
||||
You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Go or Hugo installed).
|
||||
|
||||
Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted:
|
||||
|
||||
```
|
||||
nanobox run
|
||||
```
|
||||
|
||||
|
||||
|
||||
Once inside the console use the following steps to create a new Hugo application:
|
||||
|
||||
```
|
||||
# cd into the /tmp dir to create an app
|
||||
cd /tmp
|
||||
|
||||
# generate the hugo app
|
||||
hugo new site app
|
||||
|
||||
# cd back into the /app dir
|
||||
cd -
|
||||
|
||||
# copy the generated app into the project
|
||||
shopt -s dotglob
|
||||
cp -a /tmp/app/* .
|
||||
```
|
||||
|
||||
### Install a theme
|
||||
|
||||
`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo:
|
||||
|
||||
```
|
||||
cd themes
|
||||
git clone https://github.com/sdomino/nanobox-hugo-theme
|
||||
```
|
||||
|
||||
To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml`
|
||||
|
||||
```
|
||||
# copy the config.toml that comes with the theme
|
||||
cp ./themes/nanobox-hugo-theme/config.toml config.toml
|
||||
|
||||
# or, add it to your existing config.toml
|
||||
theme = "nanobox-hugo-theme"
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced.
|
||||
{{% /note %}}
|
||||
|
||||
### View Your App
|
||||
|
||||
To view your application simply run the following command from a Nanobox console:
|
||||
|
||||
```
|
||||
hugo server --bind="0.0.0.0" --baseUrl=$APP_IP
|
||||
```
|
||||
|
||||
|
||||
|
||||
With that you should be able to visit your app at the given IP:1313 address
|
||||
|
||||
{{% note %}}
|
||||
You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313)
|
||||
{{% /note %}}
|
||||
|
||||
### Develop, Develop, Develop
|
||||
|
||||
{{% note %}}
|
||||
IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox.
|
||||
{{% /note %}}
|
||||
|
||||
With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy!
|
||||
|
||||
|
||||
## Deploying Hugo with Nanobox
|
||||
|
||||
{{% note %}}
|
||||
If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard.
|
||||
{{% /note %}}
|
||||
|
||||
To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command:
|
||||
|
||||
```
|
||||
nanobox remote add <your-app-name>
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
You may be prompted to login using your ***Nanobox credentials*** at this time
|
||||
{{% /note %}}
|
||||
|
||||
### Stage Your Application (optional)
|
||||
|
||||
Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to!
|
||||
|
||||
To stage your app simply run:
|
||||
|
||||
```
|
||||
nanobox deploy dry-run
|
||||
```
|
||||
|
||||
Now visit your application with the IP address provided.
|
||||
|
||||
|
||||
|
||||
### Deploy Your Application
|
||||
|
||||
Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run:
|
||||
|
||||
```
|
||||
nanobox deploy
|
||||
```
|
||||
|
||||
Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it!
|
||||
157
docs/content/en/hosting-and-deployment/deployment-with-rsync.md
Normal file
157
docs/content/en/hosting-and-deployment/deployment-with-rsync.md
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Deployment with Rsync
|
||||
linktitle: Deployment with Rsync
|
||||
description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2019-10-03
|
||||
categories: [hosting and deployment]
|
||||
keywords: [rsync,deployment]
|
||||
authors: [Adrien Poupin]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 70
|
||||
weight: 70
|
||||
sections_weight: 70
|
||||
draft: false
|
||||
aliases: [/tutorials/deployment-with-rsync/]
|
||||
toc: true
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
|
||||
* A web host running a web server. This could be a shared hosting environment or a VPS.
|
||||
* Access to your web host with SSH
|
||||
* A functional static website built with Hugo
|
||||
|
||||
The spoiler is that you can deploy your entire website with a command that looks like the following:
|
||||
|
||||
```
|
||||
hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/
|
||||
```
|
||||
|
||||
As you will see, we'll put this command in a shell script file, which makes building and deployment as easy as executing `./deploy`.
|
||||
|
||||
## Copy Your SSH Key to your Host
|
||||
|
||||
To make logging in to your server more secure and less interactive, you can upload your SSH key. If you have already installed your SSH key to your server, you can move on to the next section.
|
||||
|
||||
First, install the ssh client. On Debian/Ubuntu/derivates, use the following command:
|
||||
|
||||
{{< code file="install-openssh.sh" >}}
|
||||
sudo apt-get install openssh-client
|
||||
{{< /code >}}
|
||||
|
||||
Then generate your ssh key. First, create the `.ssh` directory in your home directory if it doesn't exist:
|
||||
|
||||
```
|
||||
~$ cd && mkdir .ssh & cd .ssh
|
||||
```
|
||||
|
||||
Next, execute this command to generate a new keypair called `rsa_id`:
|
||||
|
||||
```
|
||||
~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id
|
||||
```
|
||||
|
||||
You'll be prompted for a passphrase, which is an extra layer of protection. Enter the passphrase you'd like to use, and then enter it again when prompted, or leave it blank if you don't want to have a passphrase. Not using a passphrase will let you transfer files non-interactively, as you won't be prompted for a password when you log in, but it is slightly less secure.
|
||||
|
||||
To make logging in easier, add a definition for your web host to the file `~/.ssh/config` with the following command, replacing `HOST` with the IP address or hostname of your web host, and `USER` with the username you use to log in to your web host when transfering files:
|
||||
|
||||
```
|
||||
~/.ssh/$ cat >> config <<EOF
|
||||
Host HOST
|
||||
Hostname HOST
|
||||
Port 22
|
||||
User USER
|
||||
IdentityFile ~/.ssh/rsa_id
|
||||
EOF
|
||||
```
|
||||
|
||||
Then copy your ssh public key to the remote server with the `ssh-copy-id` command:
|
||||
|
||||
```
|
||||
~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com
|
||||
```
|
||||
|
||||
Now you can easily connect to the remote server:
|
||||
|
||||
```
|
||||
~$ ssh user@host
|
||||
Enter passphrase for key '/home/mylogin/.ssh/rsa_id':
|
||||
```
|
||||
|
||||
Now that you can log in with your SSH key, let's create a script to automate deployment of your Hugo site.
|
||||
|
||||
## Shell Script
|
||||
|
||||
Create a new script called `deploy` the root of your Hugo tree:
|
||||
|
||||
```
|
||||
~/websites/topologix.fr$ editor deploy
|
||||
```
|
||||
|
||||
Add the following content. Replace the `USER`, `HOST`, and `DIR` values with your own values:
|
||||
|
||||
```
|
||||
#!/bin/sh
|
||||
USER=my-user
|
||||
HOST=my-server.com
|
||||
DIR=my/directory/to/topologix.fr/ # the directory where your web site files should go
|
||||
|
||||
hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR}
|
||||
|
||||
exit 0
|
||||
```
|
||||
|
||||
Note that `DIR` is the relative path from the remote user's home. If you have to specify a full path (for instance `/var/www/mysite/`) you must change `~/${DIR}` to `${DIR}` inside the command line. For most cases you should not have to.
|
||||
|
||||
Save and close, and make the `deploy` file executable:
|
||||
|
||||
```
|
||||
~/websites/topologix.fr$ chmod +x deploy
|
||||
```
|
||||
|
||||
Now you only have to enter the following command to deploy and update your website:
|
||||
|
||||
```
|
||||
~/websites/topologix.fr$ ./deploy
|
||||
```
|
||||
|
||||
Your site builds and deploys:
|
||||
|
||||
```
|
||||
Started building sites ...
|
||||
Built site for language en:
|
||||
0 draft content
|
||||
0 future content
|
||||
0 expired content
|
||||
5 pages created
|
||||
0 non-page files copied
|
||||
0 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
total in 56 ms
|
||||
sending incremental file list
|
||||
404.html
|
||||
index.html
|
||||
index.xml
|
||||
sitemap.xml
|
||||
cours-versailles/index.html
|
||||
exercices/index.html
|
||||
exercices/index.xml
|
||||
exercices/barycentre-et-carres-des-distances/index.html
|
||||
posts/
|
||||
posts/index.html
|
||||
sujets/index.html
|
||||
sujets/index.xml
|
||||
sujets/2016-09_supelec-jp/index.html
|
||||
tarifs-contact/index.html
|
||||
|
||||
sent 9,550 bytes received 1,708 bytes 7,505.33 bytes/sec
|
||||
total size is 966,557 speedup is 85.86
|
||||
```
|
||||
|
||||
You can incorporate other proprocessing tasks into this deployment script as well.
|
||||
@@ -0,0 +1,324 @@
|
||||
---
|
||||
title: Deployment with Wercker
|
||||
linktitle: Deployment with Wercker
|
||||
description: You can use a free tool called Wercker to automate deployments between your GitHub-hosted source and final website on GitHub pages.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [hosting and deployment]
|
||||
keywords: [wercker,deployment,github,git]
|
||||
authors: [Arjen Schwarz, Samuel Debruyn]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 60
|
||||
weight: 60
|
||||
sections_weight: 60
|
||||
draft: false
|
||||
aliases: [/tutorials/automated-deployments/]
|
||||
toc: true
|
||||
wip: false
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
## Goals
|
||||
|
||||
By the end of this guide, you will have completed the following:
|
||||
|
||||
* Creating a basic Hugo project and website
|
||||
* Version controlling your project with Git
|
||||
* Adding your project to GitHub
|
||||
* Automating site deployments with a free tool called Wercker
|
||||
* Deploying your website to GitHub Pages for free hosting
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. You have a working familiarity with using Git for version control
|
||||
2. You have a GitHub account
|
||||
3. You have already created a basic Hugo project
|
||||
|
||||
If you do not meet these assumptions, the [GitHub help section][githubhelp] has an explanation of how to install and use git. [Signing up for a GitHub][ghsignup] account is free as well. If you are completely unfamiliar with creating a new Hugo website, visit the [Hugo Quick Start][quickstart].
|
||||
|
||||
## Create a Basic Hugo Site
|
||||
|
||||
{{% note "This Guide Uses the Hugo CLI" %}}
|
||||
All the work for setting up a Hugo project and using this guide is done via the Hugo CLI's most basic commands. See the [command line reference page](/commands/) for a more exhaustive account of the CLI's features.
|
||||
{{% /note %}}
|
||||
|
||||
First, create your new Hugo website using the [`hugo new site` command][basicusage] and change into the newly created directory for the project. In this guide, we are calling our new project `hugo-wercker-example`:
|
||||
|
||||
{{< code file="hugo-new-site.sh" >}}
|
||||
hugo new site hugo-wercker-example
|
||||
cd hugo-wercker-example
|
||||
{{< /code >}}
|
||||
|
||||
We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory.
|
||||
|
||||
{{< code file="clone-herring-cove-theme.sh" >}}
|
||||
cd themes
|
||||
git clone https://github.com/spf13/herring-cove.git
|
||||
{{< /code >}}
|
||||
|
||||
Cloning the project from the command line will conflict with our own version control. So, we need to remove the external git configuration that came with the clone of Herring Cove:
|
||||
|
||||
{{< code file="remove-herring-cove-git.sh" >}}
|
||||
rm -rf herring-cove/.git
|
||||
{{< /code >}}
|
||||
|
||||
We need content for Hugo to build. Let's add a quick `/about` page:
|
||||
|
||||
```
|
||||
hugo new about.md
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
The preceding example for the about page leverages archetypes to scaffold a new content file with preconfigured front matter. [Find out more about Hugo's archetypes](/content-management/archetypes/).
|
||||
{{% /note %}}
|
||||
|
||||
Now you can edit `contents/about.md` in your text editor of choice, but this is not necessary for the purposes of this guide. Running the following command will build your Hugo site into the `public` directory.
|
||||
|
||||
Once the website is build, it's a good idea to run the following command to start a local server and ensure you're changes have been implemented:
|
||||
|
||||
```
|
||||
hugo server --theme=herring-cove
|
||||
```
|
||||
|
||||
If everything is fine, you should see something similar to the image below when you go to <http://localhost:1313> in your browser.
|
||||
|
||||
![][1]
|
||||
|
||||
## Set up Version Control in Git
|
||||
|
||||
Adding Git to your project is done by running the `git init` command from the root directory of your project.
|
||||
|
||||
```
|
||||
git init
|
||||
```
|
||||
|
||||
Running `git status` at this point will show you the following entries: the `config.toml` file, the `themes` directory, the `contents` directory, and the `public` directory. However, we don't want the `public` directory version controlled because Wercker is responsible for generating the finished website later on. Therefore, we'll add a `.gitignore` file to our project that will exclude the `/public` directory from being tracked by Git:
|
||||
|
||||
{{< code file="gitignore.sh" >}}
|
||||
echo "/public" >> .gitignore
|
||||
{{< /code >}}
|
||||
|
||||
Wercker might complain when we try to build the site later on because we currently do not have any static files outside of the `themes` directory. We simply have to add *any* file to the static folder to prevent Wercker from complaining. To keep this guide simple, let's add a `robots.txt`. The following command creates the file in `/static`. The contents of the `robots.txt` lets search engines know they have full access to crawl the published website:
|
||||
|
||||
{{< code file="addrobotstxt.sh" >}}
|
||||
echo "User-agent: *\nDisallow:" > static/robots.txt
|
||||
{{< /code >}}
|
||||
|
||||
Now we need to add (i.e., [stage [see Git documentation]][gitbasics]) and commit all of our changes in the repository into Git:
|
||||
|
||||
```
|
||||
git commit -a -m "Initial commit"
|
||||
```
|
||||
|
||||
## Add the Project to GitHub
|
||||
|
||||
Now we need to create a new repository on GitHub. Once you are signed in to GitHub, you can add a new repository by clicking on the **+▼** dropdown at the top right or by going to [https://github.com/new](https://github.com)..
|
||||
|
||||
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. Be sure to replace `YourUserName` with your GitHub account/username:
|
||||
|
||||
{{< code file="setup-gh-repo.sh" >}}
|
||||
git remote add origin git@github.com:YourUsername/hugo-wercker-example.git
|
||||
git push -u origin master
|
||||
{{< /code >}}
|
||||
|
||||
![][2]
|
||||
|
||||
## Set Up Wercker
|
||||
|
||||
To sign up for a free Wercker account, go to <https://www.wercker.com> and click the **Sign Up** button on the top right of the home screen.
|
||||
|
||||
![][3]
|
||||
|
||||
### Register for Wercker with Your GitHub Account
|
||||
|
||||
Sign up for Wercker using your GitHub credentials. If you don't have a GitHub account, or don't want to use it for your account, you have the option to register with a username and password as well. However, the second half of this guide---devoted to hosting your website on GitHub pages---will no longer be of interest to you.
|
||||
|
||||
![][4]
|
||||
|
||||
### Connect GitHub or Bitbucket
|
||||
|
||||
After you are registered, you will need to link your GitHub or Bitbucket account to Wercker. You can link your account by navigating to your profile settings and then selecting "Git connections."
|
||||
|
||||
![][17]
|
||||
|
||||
If you registered for Wercker using GitHub, it will most likely look like the following image. To connect a missing service, click the **Connect** button, which may send you to either GitHub or Bitbucket to sign into your respective account.
|
||||
|
||||
![][5]
|
||||
|
||||
### 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 **+ Create** button next to Applications and choose GitHub as our provider.
|
||||
|
||||
![][6]
|
||||
|
||||
### Select a Repository
|
||||
|
||||
When selecting GitHub, Wercker will show all your GitHub repositories. You have the option to filter repositories using the search input at the top of the repositories list. Once you have your repository selected, click the **Use selected repo** button.
|
||||
|
||||
![][7]
|
||||
|
||||
### Select the Repository Owner
|
||||
|
||||
In the next step, Wercker asks you to select the repository owner. Select your GitHub account and continue.
|
||||
|
||||
![][8]
|
||||
|
||||
### Configure Access
|
||||
|
||||
{{% note %}}
|
||||
This guide assumes you are using a public GitHub repository and understand that the [published GitHub Pages website will be available to everyone](https://help.github.com/articles/what-is-github-pages/#usage-limits).
|
||||
{{%/note %}}
|
||||
|
||||
This step can be slightly tricky. Wercker does not have privileges to check out your private projects by default and therefore needs your permission to add a deploy key to your repository. By selecting the first option, you're simply allowing Wercker to check out the code via the same methods available to anyone visiting the project on GitHub.
|
||||
|
||||
![][9]
|
||||
|
||||
### Wercker.yml
|
||||
|
||||
Wercker will now attempt to create an initial `wercker.yml` file for you. More specifically, it will create a code block within the Wercker interface that you can copy to your finished file. Wercker gives us a `debian` box because our project does not have any special requirements.
|
||||
|
||||
Now we need to create a *wercker.yml* file in the root of our project. This file will contain our Wercker app's configuration. After we finish setting up our app, we will expand the contents of this file to build and deploy our website.
|
||||
|
||||
![][10]
|
||||
|
||||
### Public or Private
|
||||
|
||||
This is a personal choice. You can make an app public so that everyone can see more details about it. Keeping it private or public does not provide any overt benefits for you as the creator of the app. That said, [the app we are currently creating has been made public][publicappurl] to facilitate easier usage of this hosting and deployment guide.
|
||||
|
||||
![][11]
|
||||
|
||||
#### App Successfully Created
|
||||
|
||||
The application is now added and Wercker will offer you the chance to trigger a build. However, we will decline the offer because we haven't yet pushed our `wercker.yml` file to our GitHub repository.
|
||||
|
||||
![][12]
|
||||
|
||||
### Add the Hugo-build Step
|
||||
|
||||
Now we need to add the Wercker steps to our build process. First, we go to the "Registry" action in the top menu. When in the registry, we can search for "hugo build". Select the "Hugo-Build by **arjen**" step.
|
||||
|
||||
![][13]
|
||||
|
||||
### Use the Hugo-build Step
|
||||
|
||||
A summary of very basic usage is available at the top of the details for the Hugo-Build step. Below the basic usage is the contents of the `README.md` file associated with the step's repository. `README.md`'s on Wercker usually contain more details about the advanced options and examples of usage.
|
||||
|
||||
We're not going to use any of the advanced features of Hugo-Build in this guide. Let's return to our project and add the first section of details we need to our `wercker.yml`.
|
||||
|
||||
{{% warning "Hugo Version in `wercker.yml`" %}}
|
||||
The docs are a work in progress. As such, the `version` represented in this guide may not represent the version you've been using for local development. Be sure to use the appropriate Hugo version for your build step.
|
||||
{{% /warning %}}
|
||||
|
||||
{{< code file="wercker-build-step.yml" >}}
|
||||
box: debian
|
||||
build:
|
||||
steps:
|
||||
- arjen/hugo-build:
|
||||
version: "0.17"
|
||||
theme: herring-cove
|
||||
flags: --buildDrafts=true
|
||||
{{< /code >}}
|
||||
|
||||
We can conclude this first step by pushing our `wercker.yml` to our GitHub repository and then seeing the magic at work within Wercker's interface.
|
||||
|
||||
{{< code file="push-wecker-to-gh.sh" >}}
|
||||
git commit -a -m "Add wercker.yml"
|
||||
git push origin master
|
||||
{{< /code >}}
|
||||
|
||||
If completed and successful, a green check mark should appear in the commit column of your first build. However, this is only the build step. We still need to deploy the website to our free hosting on GitHub Pages. If you would like more details about the build, you can click the commit hash.
|
||||
|
||||
![][14]
|
||||
|
||||
### Add a GitHub Pages Deploy Step to `wercker.yml`
|
||||
|
||||
In order to deploy to GitHub Pages, we need to add a deploy step to our `wercker.yml`. We are going to add `lukevevier/gh-pages`, the most popular GitHub Pages step in the Wercker Steps repository. Additionally, we need to ensure the box Wercker uses for our deployments has git and ssh installed. We can do this using the `install-packages` command. Here is our *final* `wercker.yml` file:
|
||||
|
||||
{{< code file="wercker.yml" >}}
|
||||
box: debian
|
||||
build:
|
||||
steps:
|
||||
- arjen/hugo-build:
|
||||
version: "0.17"
|
||||
theme: herring-cove
|
||||
flags: --buildDrafts=true
|
||||
deploy:
|
||||
steps:
|
||||
- install-packages:
|
||||
packages: git ssh-client
|
||||
- lukevivier/gh-pages@0.2.1:
|
||||
token: $GIT_TOKEN
|
||||
domain: hugo-wercker.ig.nore.me
|
||||
basedir: public
|
||||
{{< /code >}}
|
||||
|
||||
### How does the GitHub Pages Configuration Work?
|
||||
|
||||
We've provided a some important information in our `wercker.yml`. First, we've added the domain we want to use for our published website. Configuring the domain here will ensure that GitHub Pages is aware of the domain we want to use.
|
||||
|
||||
Secondly, we've configured the `basedir` to `public`. This is the directory that will be used as the website on GitHub Pages. `public` is also the default publishing directory in Hugo. (For more information, see [hugo's configuration docs][hugoconfig]).
|
||||
|
||||
Lastly, you'll notice a `$GIT_TOKEN` variable. This is used for pushing our changes to GitHub. We will need to configure this token before Wercker can build our website.
|
||||
|
||||
### Set the App's Deploy Target
|
||||
|
||||
We can set our deploy target by going to our app's settings and clicking on **Deploy targets**. Now select **Add deploy target** and then **Custom deploy**.
|
||||
|
||||
![][15]
|
||||
|
||||
### Configure the Deploy Step in Wercker
|
||||
|
||||
The next screen requires you fill in the deploy target name.
|
||||
|
||||
1. Make sure you enable **auto deploy** from the **master** branch.
|
||||
2. Add a variable for the **GIT_TOKEN**. You'll need to create an access token in GitHub. Follow the directions in [GitHub help][accesstokenghhelp].
|
||||
3. 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 website described in this guide is available at <http://hugo-wercker.ig.nore.me>.
|
||||
|
||||
![][16]
|
||||
|
||||
## Conclusion
|
||||
|
||||
Once this workflow is established, you can update your website automatically by pushing any content changes to your GitHub repository.
|
||||
|
||||
### Code for the Wercker Deployment Guide
|
||||
|
||||
[The source code for the site used in this guide is available on GitHub][guidesource], as is the [Wercker Hugo Build step][guidestep].
|
||||
|
||||
If you want to see an example of how you can deploy to S3 instead of GitHub pages, check [Wercker's documentation][werckerdocs] for guidance on setup.
|
||||
|
||||
[1]: /images/hosting-and-deployment/deployment-with-wercker/creating-a-basic-hugo-site.png
|
||||
[2]: /images/hosting-and-deployment/deployment-with-wercker/adding-the-project-to-github.png
|
||||
[3]: /images/hosting-and-deployment/deployment-with-wercker/wercker-sign-up.png
|
||||
[4]: /images/hosting-and-deployment/deployment-with-wercker/wercker-sign-up-page.png
|
||||
[5]: /images/hosting-and-deployment/deployment-with-wercker/wercker-git-connections.png
|
||||
[6]: /images/hosting-and-deployment/deployment-with-wercker/wercker-add-app.png
|
||||
[7]: /images/hosting-and-deployment/deployment-with-wercker/wercker-select-repository.png
|
||||
[8]: /images/hosting-and-deployment/deployment-with-wercker/wercker-select-owner.png
|
||||
[9]: /images/hosting-and-deployment/deployment-with-wercker/wercker-access.png
|
||||
[10]: /images/hosting-and-deployment/deployment-with-wercker/werckeryml.png
|
||||
[11]: /images/hosting-and-deployment/deployment-with-wercker/public-or-not.png
|
||||
[12]: /images/hosting-and-deployment/deployment-with-wercker/and-we-ve-got-an-app.png
|
||||
[13]: /images/hosting-and-deployment/deployment-with-wercker/wercker-search.png
|
||||
[14]: /images/hosting-and-deployment/deployment-with-wercker/using-hugo-build.png
|
||||
[15]: /images/hosting-and-deployment/deployment-with-wercker/adding-a-github-pages-step.png
|
||||
[16]: /images/hosting-and-deployment/deployment-with-wercker/configure-the-deploy-step.png
|
||||
[17]: /images/hosting-and-deployment/deployment-with-wercker/wercker-account-settings.png
|
||||
|
||||
|
||||
[accesstokenghhelp]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
|
||||
[basicusage]: /getting-started/usage/
|
||||
[ghsignup]: https://github.com/join
|
||||
[gitbasics]: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics
|
||||
[githubhelp]: https://help.github.com/articles/set-up-git/
|
||||
[guidesource]: https://github.com/ArjenSchwarz/hugo-wercker-example
|
||||
[guidestep]: https://github.com/ArjenSchwarz/wercker-step-hugo-build
|
||||
[Herring Cove theme]: https://github.com/spf13/herring-cove
|
||||
[hugoconfig]: /getting-started/configuration/
|
||||
[publicappurl]: https://app.wercker.com/#applications/5586dcbdaf7de9c51b02b0d5
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
[werckerdocs]: http://devcenter.wercker.com/docs/deploy/s3.html
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Host on AWS Amplify
|
||||
linktitle: Host on AWS Amplify
|
||||
description: Develop and deploy a cloud-powered web app with AWS Amplify.
|
||||
date: 2018-01-31
|
||||
publishdate: 2018-01-31
|
||||
lastmod: 2018-01-31
|
||||
categories: [hosting and deployment]
|
||||
keywords: [amplify,hosting,deployment]
|
||||
authors: [Nikhil Swaminathan]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
In this guide we'll walk through how to deploy and host your Hugo site using the [AWS Amplify Console](https://console.amplify.aws).
|
||||
|
||||
AWS Amplify is a combination of client library, CLI toolchain, and a Console for continuous deployment and hosting. The Amplify CLI and library allow developers to get up & running with full-stack cloud-powered applications with features like authentication, storage, serverless GraphQL or REST APIs, analytics, Lambda functions, & more. The Amplify Console provides continuous deployment and hosting for modern web apps (single page apps and static site generators). Continuous deployment allows developers to deploy updates to their web app on every code commit to their Git repository. Hosting includes features such as globally available CDNs, easy custom domain setup + HTTPS, feature branch deployments, and password protection.
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
* [Sign up for an AWS Account](https://portal.aws.amazon.com/billing/signup?redirect_url=https%3A%2F%2Faws.amazon.com%2Fregistration-confirmation). There are no upfront charges or any term commitments to create an AWS account and signing up gives you immediate access to the AWS Free Tier.
|
||||
* You have an account with GitHub, GitLab, or Bitbucket.
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
|
||||
## Hosting
|
||||
|
||||
1. Log in to the [AWS Amplify Console](https://console.aws.amazon.com/amplify/home) and choose Get Started under Deploy.
|
||||
|
||||
|
||||
1. Connect a branch from your GitHub, Bitbucket, GitLab, or AWS CodeCommit repository. Connecting your repository allows Amplify to deploy updates on every code commit to a branch.
|
||||
|
||||
|
||||
1. Accept the default build settings. The Amplify Console automatically detects your Hugo build settings and output directory.
|
||||
|
||||
|
||||
1. Review your changes and then choose **Save and deploy**. The Amplify Console will pull code from your repository, build changes to the backend and frontend, and deploy your build artifacts at `https://master.unique-id.amplifyapp.com`. Bonus: Screenshots of your app on different devices to find layout issues.
|
||||
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
143
docs/content/en/hosting-and-deployment/hosting-on-bitbucket.md
Normal file
143
docs/content/en/hosting-and-deployment/hosting-on-bitbucket.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: Host on Bitbucket
|
||||
linktitle: Host on Bitbucket
|
||||
description: You can use Bitbucket in conjunction with Aerobatic to build, deploy, and host a Hugo website.
|
||||
date: 2017-02-04
|
||||
publishdate: 2017-02-04
|
||||
lastmod: 2017-02-04
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,bitbucket,deployment,aerobatic]
|
||||
authors: [Jason Gowans]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 50
|
||||
weight: 50
|
||||
sections_weight: 50
|
||||
draft: false
|
||||
toc: true
|
||||
aliases: [/tutorials/hosting-on-bitbucket/]
|
||||
---
|
||||
|
||||
You can use [Bitbucket](https://bitbucket.org/) and [Aerobatic](https://www.aerobatic.com) to build, deploy, and host a Hugo website. Aerobatic is a static hosting service that integrates with Bitbucket and provides a free hosting tier.
|
||||
|
||||
## Assumptions
|
||||
|
||||
* Working familiarity with Git for version control
|
||||
* A [Bitbucket account](https://bitbucket.org/account/signup/)
|
||||
|
||||
## Install Aerobatic CLI
|
||||
|
||||
If you haven't previously used Aerobatic, you'll first need to install the Command Line Interface (CLI) and create an account. For a list of all commands available, see the [Aerobatic CLI](https://www.aerobatic.com/docs/cli/) docs.
|
||||
|
||||
```
|
||||
npm install aerobatic-cli -g
|
||||
aero register
|
||||
```
|
||||
|
||||
## Create and Deploy Site
|
||||
|
||||
```
|
||||
hugo new site my-new-hugo-site
|
||||
cd my-new-hugo-site
|
||||
cd themes; git clone https://github.com/eliasson/liquorice
|
||||
hugo -t liquorice
|
||||
aero create # create the Aerobatic site
|
||||
hugo --baseURL https://my-new-hugo-site.aerobatic.io # build the site overriding baseURL
|
||||
aero deploy -d public # deploy output to Aerobatic
|
||||
|
||||
Version v1 deployment complete.
|
||||
View now at https://hugo-docs-test.aerobatic.io
|
||||
```
|
||||
|
||||
In the rendered page response, the `https://__baseurl__` will be replaced with your actual site url (in this example, `https://my-new-hugo-site.aerobatic.io`). You can always rename your Aerobatic website with the `aero rename` command.
|
||||
|
||||
## Push Hugo site to Bitbucket
|
||||
|
||||
We will now create a git repository and then push our code to Bitbucket. In Bitbucket, create a repository.
|
||||
|
||||
![][1]
|
||||
|
||||
[1]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-create-repo.png
|
||||
|
||||
|
||||
```
|
||||
# initialize new git repository
|
||||
git init
|
||||
|
||||
# set up our .gitignore file
|
||||
echo -e "/public \n/themes \naero-deploy.tar.gz" >> .gitignore
|
||||
|
||||
# commit and push code to master branch
|
||||
git add --all
|
||||
git commit -m "Initial commit"
|
||||
git remote add origin git@bitbucket.org:YourUsername/my-new-hugo-site.git
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
## Continuous Deployment With Bitbucket Pipelines
|
||||
|
||||
In the example above, we pushed the compiled assets in the `/public` folder to Aerobatic. In the following example, we use Bitbucket Pipelines to continuously create and deploy the compiled assets to Aerobatic.
|
||||
|
||||
### Step 1: Configure Bitbucket Pipelines
|
||||
|
||||
In your Hugo website's Bitbucket repo;
|
||||
|
||||
1. Click the Pipelines link in the left nav menu of your Bitbucket repository.
|
||||
2. Click the Enable Pipelines button.
|
||||
3. On the next screen, leave the default template and click Next.
|
||||
4. In the editor, paste in the yaml contents below and click Commit.
|
||||
|
||||
```
|
||||
image: beevelop/nodejs-python
|
||||
pipelines:
|
||||
branches:
|
||||
master:
|
||||
- step:
|
||||
script:
|
||||
- apt-get update -y && apt-get install wget
|
||||
- apt-get -y install git
|
||||
- wget https://github.com/gohugoio/hugo/releases/download/v0.18/hugo_0.18-64bit.deb
|
||||
- dpkg -i hugo*.deb
|
||||
- git clone https://github.com/eliasson/liquorice themes/liquorice
|
||||
- hugo --theme=liquorice --baseURL https://__baseurl__ --buildDrafts
|
||||
- npm install -g aerobatic-cli
|
||||
- aero deploy
|
||||
```
|
||||
|
||||
### Step 2: Create `AEROBATIC_API_KEY` environment variable.
|
||||
|
||||
This step only needs to be done once per account. From the command line;
|
||||
|
||||
```
|
||||
aero apikey
|
||||
```
|
||||
|
||||
1. Navigate to the Bitbucket account settings for the account that the website repo belongs to.
|
||||
2. Scroll down to the bottom of the left nav and click the Environment variables link in the PIPELINES section.
|
||||
3. Create a new environment variable called AEROBATIC_API_KEY with the value you got by running the `aero apikey` command. Be sure to click the Secured checkbox.
|
||||
|
||||
### Step 3: Edit and Commit Code
|
||||
|
||||
```
|
||||
hugo new posts/good-to-great.md
|
||||
hugo server --buildDrafts -t liquorice #Check that all looks good
|
||||
|
||||
# commit and push code to master branch
|
||||
git add --all
|
||||
git commit -m "New blog post"
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
Your code will be committed to Bitbucket, Bitbucket Pipelines will run your build, and a new version of your site will be deployed to Aerobatic.
|
||||
|
||||
At this point, you can now create and edit blog posts directly in the Bitbucket UI.
|
||||
|
||||
![][2]
|
||||
|
||||
[2]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-blog-post.png
|
||||
|
||||
|
||||
## Suggested next steps
|
||||
|
||||
The code for this example can be found in this Bitbucket [repository](https://bitbucket.org/dundonian/hugo-docs-test). Aerobatic also provides a number of additional [plugins](https://www.aerobatic.com/docs) such as auth and redirects that you can use for your Hugo site.
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Host on Firebase
|
||||
linktitle: Host on Firebase
|
||||
description: You can use Firebase's free tier to host your static website; this also gives you access to Firebase's NOSQL API.
|
||||
date: 2017-03-12
|
||||
publishdate: 2017-03-12
|
||||
lastmod: 2017-03-15
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,firebase]
|
||||
authors: [Michel Racic]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 20
|
||||
weight: 20
|
||||
sections_weight: 20
|
||||
draft: false
|
||||
toc: true
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. You have an account with [Firebase][signup]. (If you don't, you can sign up for free using your Google account.)
|
||||
2. You have completed the [Quick Start][] or have a completed Hugo website ready for deployment.
|
||||
|
||||
## Initial setup
|
||||
|
||||
Go to the [Firebase console][console] and create a new project (unless you already have a project). You will need to globally install `firebase-tools` (node.js):
|
||||
|
||||
|
||||
```
|
||||
npm install -g firebase-tools
|
||||
```
|
||||
|
||||
Log in to Firebase (setup on your local machine) using `firebase login`, which opens a browser where you can select your account. Use `firebase logout` in case you are already logged in but to the wrong account.
|
||||
|
||||
|
||||
```
|
||||
firebase login
|
||||
```
|
||||
In the root of your Hugo project, initialize the Firebase project with the `firebase init` command:
|
||||
|
||||
```
|
||||
firebase init
|
||||
```
|
||||
From here:
|
||||
|
||||
1. Choose Hosting in the feature question
|
||||
2. Choose the project you just set up
|
||||
3. Accept the default for your database rules file
|
||||
4. Accept the default for the publish directory, which is `public`
|
||||
5. Choose "No" in the question if you are deploying a single-page app
|
||||
|
||||
## Deploy
|
||||
|
||||
To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time:
|
||||
|
||||
```
|
||||
hugo && firebase deploy
|
||||
```
|
||||
|
||||
## CI Setup
|
||||
|
||||
You can generate a deploy token using
|
||||
|
||||
|
||||
```
|
||||
firebase login:ci
|
||||
```
|
||||
|
||||
You can also set up your CI (e.g., with [Wercker][]) and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`.
|
||||
|
||||
{{% note %}}
|
||||
This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others.
|
||||
{{% /note %}}
|
||||
|
||||
You can then add a step in your build to do the deployment using the token:
|
||||
|
||||
```
|
||||
firebase deploy --token $FIREBASE_DEPLOY_TOKEN
|
||||
```
|
||||
|
||||
## Reference links
|
||||
|
||||
* [Firebase CLI Reference](https://firebase.google.com/docs/cli/#administrative_commands)
|
||||
|
||||
[console]: https://console.firebase.google.com
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
[signup]: https://console.firebase.google.com/
|
||||
[Wercker]: /hosting-and-deployment/deployment-with-wercker/
|
||||
252
docs/content/en/hosting-and-deployment/hosting-on-github.md
Normal file
252
docs/content/en/hosting-and-deployment/hosting-on-github.md
Normal file
@@ -0,0 +1,252 @@
|
||||
---
|
||||
title: Host on GitHub
|
||||
linktitle: Host on GitHub
|
||||
description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script.
|
||||
date: 2014-03-21
|
||||
publishdate: 2014-03-21
|
||||
lastmod: 2018-09-22
|
||||
categories: [hosting and deployment]
|
||||
keywords: [github,git,deployment,hosting]
|
||||
authors: [Spencer Lyon, Gunnar Morling]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 30
|
||||
weight: 30
|
||||
sections_weight: 30
|
||||
draft: false
|
||||
toc: true
|
||||
aliases: [/tutorials/github-pages-blog/]
|
||||
---
|
||||
|
||||
GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][].
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. You have Git 2.8 or greater [installed on your machine][installgit].
|
||||
2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
|
||||
3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
|
||||
|
||||
## Types of GitHub Pages
|
||||
|
||||
There are 2 types of GitHub Pages:
|
||||
|
||||
- User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`)
|
||||
- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`)
|
||||
|
||||
Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use.
|
||||
|
||||
To create a User/Organization Pages site, follow the single method in the *GitHub User and Organization Pages* section below.
|
||||
|
||||
To create a Project Pages site, choose a method from the *Project Pages* section below.
|
||||
|
||||
## GitHub User or Organization Pages
|
||||
|
||||
As mentioned [the GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
|
||||
|
||||
1. You must use a `<USERNAME>.github.io` to host your **generated** content
|
||||
2. Content from the `master` branch will be used to publish your GitHub Pages site
|
||||
|
||||
This is a much simpler setup as your Hugo files and generated content are published into two different repositories.
|
||||
|
||||
### Step-by-step Instructions
|
||||
|
||||
1. Create a `<YOUR-PROJECT>` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files.
|
||||
2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
|
||||
3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
|
||||
4. Paste your existing Hugo project into a new local `<YOUR-PROJECT>` repository. Make sure your website works locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
|
||||
5. Once you are happy with the results:
|
||||
* Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
|
||||
* Before proceeding run `rm -rf public` to completely remove the `public` directory
|
||||
6. `git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository).
|
||||
|
||||
### Put it Into a Script
|
||||
|
||||
You're almost done. In order to automate next steps create a `deploy.sh` script. You can also make it executable with `chmod +x deploy.sh`.
|
||||
|
||||
The following are the contents of the `deploy.sh` script:
|
||||
|
||||
```
|
||||
#!/bin/sh
|
||||
|
||||
# If a command fails then the deploy stops
|
||||
set -e
|
||||
|
||||
printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"
|
||||
|
||||
# Build the project.
|
||||
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
|
||||
|
||||
# Go To Public folder
|
||||
cd public
|
||||
|
||||
# Add changes to git.
|
||||
git add .
|
||||
|
||||
# Commit changes.
|
||||
msg="rebuilding site $(date)"
|
||||
if [ -n "$*" ]; then
|
||||
msg="$*"
|
||||
fi
|
||||
git commit -m "$msg"
|
||||
|
||||
# Push source and build repos.
|
||||
git push origin master
|
||||
```
|
||||
|
||||
|
||||
You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
|
||||
|
||||
That's it! Your personal page should be up and running at `https://<USERNAME>.github.io` within a couple minutes.
|
||||
|
||||
## GitHub Project Pages
|
||||
|
||||
{{% note %}}
|
||||
Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `<USERNAME>.github.io/<PROJECT>/`) and not a custom domain.
|
||||
{{% /note %}}
|
||||
|
||||
### Deployment of Project Pages from `/docs` folder on `master` branch
|
||||
|
||||
[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
|
||||
|
||||
```
|
||||
publishDir = "docs"
|
||||
```
|
||||
```
|
||||
publishDir: docs
|
||||
```
|
||||
|
||||
After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
|
||||
|
||||
1. Go to **Settings** → **GitHub Pages**
|
||||
2. From **Source**, select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
|
||||
|
||||
{{% note %}}
|
||||
The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control.
|
||||
{{% /note %}}
|
||||
|
||||
### Deployment of Project Pages From Your `gh-pages` branch
|
||||
|
||||
You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
|
||||
|
||||
* It keeps your source and generated website in different branches and therefore maintains version control history for both.
|
||||
* Unlike the preceding `docs/` option, it uses the default `public` folder.
|
||||
|
||||
#### Preparations for `gh-pages` Branch
|
||||
|
||||
These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`:
|
||||
|
||||
##### Add the `public` Folder
|
||||
|
||||
First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
|
||||
|
||||
```
|
||||
echo "public" >> .gitignore
|
||||
```
|
||||
|
||||
##### Initialize Your `gh-pages` Branch
|
||||
|
||||
You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
|
||||
|
||||
```
|
||||
git checkout --orphan gh-pages
|
||||
git reset --hard
|
||||
git commit --allow-empty -m "Initializing gh-pages branch"
|
||||
git push upstream gh-pages
|
||||
git checkout master
|
||||
```
|
||||
|
||||
#### Build and Deployment
|
||||
|
||||
Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories:
|
||||
|
||||
```
|
||||
rm -rf public
|
||||
git worktree add -B gh-pages public upstream/gh-pages
|
||||
```
|
||||
|
||||
Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
|
||||
|
||||
{{< code file="commit-gh-pages-files.sh">}}
|
||||
hugo
|
||||
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
|
||||
{{< /code >}}
|
||||
|
||||
If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
|
||||
|
||||
```
|
||||
git push upstream gh-pages
|
||||
```
|
||||
|
||||
##### Set `gh-pages` as Your Publish Branch
|
||||
|
||||
In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project:
|
||||
|
||||
1. Go to **Settings** → **GitHub Pages**
|
||||
2. From **Source**, select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub.
|
||||
|
||||
After a short while, you'll see the updated contents on your GitHub Pages site.
|
||||
|
||||
#### Put it Into a Script
|
||||
|
||||
To automate these steps, you can create a script with the following contents:
|
||||
|
||||
{{< code file="publish_to_ghpages.sh" >}}
|
||||
#!/bin/sh
|
||||
|
||||
if [ "`git status -s`" ]
|
||||
then
|
||||
echo "The working directory is dirty. Please commit any pending changes."
|
||||
exit 1;
|
||||
fi
|
||||
|
||||
echo "Deleting old publication"
|
||||
rm -rf public
|
||||
mkdir public
|
||||
git worktree prune
|
||||
rm -rf .git/worktrees/public/
|
||||
|
||||
echo "Checking out gh-pages branch into public"
|
||||
git worktree add -B gh-pages public upstream/gh-pages
|
||||
|
||||
echo "Removing existing files"
|
||||
rm -rf public/*
|
||||
|
||||
echo "Generating site"
|
||||
hugo
|
||||
|
||||
echo "Updating gh-pages branch"
|
||||
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
|
||||
|
||||
#echo "Pushing to github"
|
||||
#git push --all
|
||||
{{< /code >}}
|
||||
|
||||
This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing.
|
||||
|
||||
### Deployment of Project Pages from Your `master` Branch
|
||||
|
||||
To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
|
||||
|
||||
You will also need to set `master` as your publishable branch from within the GitHub UI:
|
||||
|
||||
1. Go to **Settings** → **GitHub Pages**
|
||||
2. From **Source**, select "master branch" and then **Save**.
|
||||
|
||||
## Use a Custom Domain
|
||||
|
||||
If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages.
|
||||
|
||||
Refer to the [official documentation for custom domains][domains] for further information.
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
|
||||
[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages
|
||||
[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch
|
||||
[ghsignup]: https://github.com/join
|
||||
[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
|
||||
[installgit]: https://git-scm.com/downloads
|
||||
[orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
[submodule]: https://github.com/blog/2104-working-with-submodules
|
||||
[worktree feature]: https://git-scm.com/docs/git-worktree
|
||||
84
docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
Normal file
84
docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Host on GitLab
|
||||
linktitle: Host on GitLab
|
||||
description: GitLab makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
|
||||
date: 2016-06-23
|
||||
publishdate: 2016-06-23
|
||||
lastmod: 2017-11-16
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,deployment,git,gitlab]
|
||||
authors: [Riku-Pekka Silvola]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 40
|
||||
weight: 40
|
||||
sections_weight: 40
|
||||
draft: false
|
||||
toc: true
|
||||
wip: false
|
||||
aliases: [/tutorials/hosting-on-gitlab/]
|
||||
---
|
||||
|
||||
[GitLab](https://gitlab.com/) makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides [native support for Hugo, as well as numerous other static site generators](https://gitlab.com/pages/hugo).
|
||||
|
||||
## Assumptions
|
||||
|
||||
* Working familiarity with Git for version control
|
||||
* Completion of the Hugo [Quick Start][]
|
||||
* A [GitLab account](https://gitlab.com/users/sign_in)
|
||||
* A Hugo website on your local machine that you are ready to publish
|
||||
|
||||
## Create .gitlab-ci.yml
|
||||
|
||||
```
|
||||
cd your-hugo-site
|
||||
```
|
||||
|
||||
In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
|
||||
|
||||
{{< code file=".gitlab-ci.yml" >}}
|
||||
image: monachus/hugo
|
||||
|
||||
variables:
|
||||
GIT_SUBMODULE_STRATEGY: recursive
|
||||
|
||||
pages:
|
||||
script:
|
||||
- hugo
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
only:
|
||||
- master
|
||||
{{< /code >}}
|
||||
|
||||
## Push Your Hugo Website to GitLab
|
||||
|
||||
Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
|
||||
|
||||
```
|
||||
# initialize new git repository
|
||||
git init
|
||||
|
||||
# add /public directory to our .gitignore file
|
||||
echo "/public" >> .gitignore
|
||||
|
||||
# commit and push code to master branch
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
## Wait for Your Page to Build
|
||||
|
||||
That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`.
|
||||
|
||||
After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
|
||||
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
94
docs/content/en/hosting-and-deployment/hosting-on-keycdn.md
Normal file
94
docs/content/en/hosting-and-deployment/hosting-on-keycdn.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: "Hosting on KeyCDN"
|
||||
date: 2017-09-12
|
||||
description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to setup your static site as a GitLab page behind a KeyCDN pull zone."
|
||||
categories: [hosting and deployment]
|
||||
keywords: [keycdn,hosting,deployment,cdn]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 40
|
||||
slug: ""
|
||||
aliases: []
|
||||
toc: false
|
||||
draft: false
|
||||
---
|
||||
|
||||
[KeyCDN](https://www.keycdn.com/) provides a multitude of features to help accelerate and secure your Hugo site globally including Brotli compression, Let's Encrypt support, Origin Shield, and more.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- You already have a Hugo page configured
|
||||
- You have a GitLab account
|
||||
- You have a KeyCDN account
|
||||
|
||||
## Create a KeyCDN Pull Zone
|
||||
|
||||
The first step will be to login to your KeyCDN account and create a new zone. Name this whatever you like and select the [Pull Zone](https://www.keycdn.com/support/create-a-pull-zone/) option. As for the origin URL, your site will be running on [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html) with a URL of `https://youruser.gitlab.io/reponame/`. Use this as the Origin URL.
|
||||
|
||||
|
||||
|
||||
While the origin location doesn’t exist yet, you will need to use your new Zone URL address (or [Zonealias](https://www.keycdn.com/support/create-a-zonealias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project.
|
||||
|
||||
Ensure that you use your Zone URL or Zonealias as the `BASEURL` variable in the example below. This will be the user-visible website address.
|
||||
|
||||
## Configure Your .gitlab-ci.yml File
|
||||
|
||||
Your `.gitlab-ci.yml` file should look similar to the example below. Be sure to modify any variables that are specific to your setup.
|
||||
|
||||
```
|
||||
image: alpine:latest
|
||||
|
||||
variables:
|
||||
BASEURL: "https://cipull-7bb7.kxcdn.com/"
|
||||
HUGO_VERSION: "0.26"
|
||||
HUGO_CHECKSUM: "67e4ba5ec2a02c8164b6846e30a17cc765b0165a5b183d5e480149baf54e1a50"
|
||||
KEYCDN_ZONE_ID: "75544"
|
||||
|
||||
before_script:
|
||||
- apk update
|
||||
- apk add curl
|
||||
|
||||
pages:
|
||||
stage: deploy
|
||||
script:
|
||||
- apk add git
|
||||
- git submodule update --init
|
||||
- curl -sSL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz -o /tmp/hugo.tar.gz
|
||||
- echo "${HUGO_CHECKSUM} /tmp/hugo.tar.gz" | sha256sum -c
|
||||
- tar xf /tmp/hugo.tar.gz hugo -C /tmp/ && cp /tmp/hugo /usr/bin
|
||||
- hugo --baseURL ${BASEURL}
|
||||
- curl "https://api.keycdn.com/zones/purge/${KEYCDN_ZONE_ID}.json" -u "${KEYCDN_API_KEY}:"
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
only:
|
||||
- master
|
||||
|
||||
```
|
||||
Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section.
|
||||
|
||||
The Secret Variable for your Zone ID should look similar to:
|
||||
|
||||
|
||||
|
||||
While the Secret Variable for your API Key will look similar to:
|
||||
|
||||
|
||||
|
||||
The Zone ID and API key are used to purge your zone – it’s not strictly needed but otherwise, the CDN might deliver older versions of your assets for quite a while.
|
||||
|
||||
## Push Your Changes to GitLab
|
||||
|
||||
Now it’s time to push the newly created repository to GitLab:
|
||||
|
||||
```
|
||||
git remote add origin git@gitlab.com:youruser/ciexample.git
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
You can watch the progress and CI job output in your Gitlab project under “Pipelines”.
|
||||
|
||||
After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone – don’t worry about that) and then by heading to whatever Zonealias / Zone URL you defined.
|
||||
|
||||
To learn more about Hugo hosting options with KeyCDN, check out the complete [Hugo hosting with KeyCDN integration guide](https://www.keycdn.com/support/hugo-hosting/).
|
||||
159
docs/content/en/hosting-and-deployment/hosting-on-netlify.md
Normal file
159
docs/content/en/hosting-and-deployment/hosting-on-netlify.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Host on Netlify
|
||||
linktitle: Host on Netlify
|
||||
description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-03-11
|
||||
categories: [hosting and deployment]
|
||||
keywords: [netlify,hosting,deployment]
|
||||
authors: [Ryan Watters, Seth MacLeod]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website.
|
||||
|
||||
## Assumptions
|
||||
|
||||
* You have an account with GitHub, GitLab, or Bitbucket.
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You do not already have a Netlify account.
|
||||
|
||||
## Create a Netlify account
|
||||
|
||||
Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address.
|
||||
|
||||
The following examples use GitHub, but other git providers will follow a similar process.
|
||||
|
||||
|
||||
|
||||
Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application."
|
||||
|
||||
|
||||
|
||||
## Create a New Site with Continuous Deployment
|
||||
|
||||
You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git."
|
||||
|
||||
|
||||
|
||||
Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories.
|
||||
|
||||
|
||||
|
||||
And then again with the GitHub authorization modal:
|
||||
|
||||
|
||||
|
||||
Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search:
|
||||
|
||||
|
||||
|
||||
Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
|
||||
|
||||
## Configure Hugo Version in Netlify
|
||||
|
||||
You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
|
||||
|
||||
For production:
|
||||
|
||||
```
|
||||
[context.production.environment]
|
||||
HUGO_VERSION = "0.53"
|
||||
```
|
||||
|
||||
For testing:
|
||||
|
||||
```
|
||||
[context.deploy-preview.environment]
|
||||
HUGO_VERSION = "0.53"
|
||||
```
|
||||
|
||||
The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:
|
||||
|
||||
{{< code file="netlify.toml" nocode="true" >}}
|
||||
{{< readfile file="netlify.toml" highlight="toml" >}}
|
||||
{{< /code >}}
|
||||
|
||||
## Build and Deploy Site
|
||||
|
||||
In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:.
|
||||
|
||||
|
||||
|
||||
Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings."
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[Visit the live site][visit].
|
||||
|
||||
Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site.
|
||||
|
||||
See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions.
|
||||
|
||||
## Use Hugo Themes with Netlify
|
||||
|
||||
The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme.
|
||||
|
||||
A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`:
|
||||
|
||||
```
|
||||
cd themes
|
||||
git submodule add https://github.com/<THEMECREATOR>/<THEMENAME>
|
||||
```
|
||||
|
||||
It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory.
|
||||
|
||||
Switch to the theme's directory and list all available versions:
|
||||
|
||||
```
|
||||
cd themes/<theme>
|
||||
git tag
|
||||
# exit with q
|
||||
```
|
||||
|
||||
You can checkout a specific version as follows:
|
||||
|
||||
```
|
||||
git checkout tags/<version-name>
|
||||
```
|
||||
|
||||
You can update a theme to the latest version by executing the following command in the *root* directory of your project:
|
||||
|
||||
```
|
||||
git submodule update --rebase --remote
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
You now have a live website served over https, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation:
|
||||
|
||||
1. [Using a Custom Domain][]
|
||||
2. [Setting up HTTPS on Custom Domains][httpscustom]
|
||||
3. [Redirects and Rewrite Rules][]
|
||||
|
||||
|
||||
[app.netlify.com]: https://app.netlify.com
|
||||
[build command]: /getting-started/usage/#the-hugo-command
|
||||
[config]: /getting-started/configuration/
|
||||
[ghsm]: https://github.com/blog/2104-working-with-submodules
|
||||
[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
|
||||
[httpscustom]: https://www.netlify.com/docs/ssl/
|
||||
[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216
|
||||
[installthemes]: /themes/installing/
|
||||
[netlify]: https://www.netlify.com/
|
||||
[netlifysignup]: https://app.netlify.com/signup
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/
|
||||
[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/
|
||||
[visit]: https://hugo-netlify-example.netlify.com
|
||||
93
docs/content/en/hosting-and-deployment/hosting-on-render.md
Normal file
93
docs/content/en/hosting-and-deployment/hosting-on-render.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Host on Render
|
||||
linktitle: Host on Render
|
||||
description: Host your Hugo site for free with Render's global CDN, fully-managed SSL and auto deploys from GitHub.
|
||||
date: 2019-06-06
|
||||
publishdate: 2019-06-06
|
||||
lastmod: 2019-06-21
|
||||
categories: [hosting and deployment]
|
||||
keywords: [render,hosting,deployment]
|
||||
authors: [Anurag Goel]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
[Render](https://render.com) is a fully-managed cloud platform where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place.
|
||||
|
||||
Static sites are **completely free** on Render and include the following:
|
||||
|
||||
- Continuous, automatic builds & deploys from GitHub.
|
||||
- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org).
|
||||
- Instant cache invalidation with a lightning fast, global CDN.
|
||||
- Unlimited collaborators.
|
||||
- Unlimited [custom domains](https://render.com/docs/custom-domains).
|
||||
- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites.
|
||||
- Native HTTP/2 support.
|
||||
- [Pull Request Previews](https://render.com/docs/pull-request-previews).
|
||||
- Automatic HTTP → HTTPS redirects.
|
||||
- Custom URL redirects and rewrites.
|
||||
|
||||
## Assumptions
|
||||
|
||||
* You have an account with GitHub.
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You have a Render account. You can sign up at https://render.com/register.
|
||||
|
||||
## Deployment
|
||||
|
||||
You can set up a Hugo site on Render in two quick steps:
|
||||
|
||||
1. Create a new **Web Service** on Render, and give Render permission to access your GitHub repo.
|
||||
2. Use the following values during creation:
|
||||
|
||||
Field | Value
|
||||
------------------- | -------------------
|
||||
**Environment** | `Static Site`
|
||||
**Build Command** | `hugo --gc --minify` (or our own build command)
|
||||
**Publish Directory** | `public` (or your own output directory)
|
||||
|
||||
That's it! Your site will be live on your Render URL (which looks like `yoursite.onrender.com`) as soon as the build is done.
|
||||
|
||||
## Continuous Deploys
|
||||
|
||||
Now that Render is connected to your repo, it will **automatically build and publish your site** any time you push to GitHub.
|
||||
|
||||
You can choose to disable auto deploys under the **Settings** section for your site and deploy it manually from the Render dashboard.
|
||||
|
||||
## CDN and Cache Invalidation
|
||||
|
||||
Render hosts your site on a global, lightning fast CDN which ensures the fastest possible download times for all your users across the globe.
|
||||
|
||||
Every deploy automatically and instantly invalidates the CDN cache, so your users can always access the latest content on your site.
|
||||
|
||||
## Custom Domains
|
||||
|
||||
Add your own domains to your site easily using Render's [custom domains](https://render.com/docs/custom-domains) guide.
|
||||
|
||||
## Pull Request Previews
|
||||
|
||||
With Pull Request (PR) previews, you can visualize changes introduced in a pull request instead of simply relying on code reviews.
|
||||
|
||||
Once enabled, every PR for your site will automatically generate a new static site based on the code in the PR. It will have its own URL, and it will be deleted automatically when the PR is closed.
|
||||
|
||||
Read more about [Pull Request Previews](https://render.com/docs/pull-request-previews) on Render.
|
||||
|
||||
## Hugo Themes
|
||||
|
||||
Render automatically downloads all Git submodules defined in your Git repo on every build. This way Hugo themes added as submodules work as expected.
|
||||
|
||||
## Support
|
||||
|
||||
Chat with Render developers at https://render.com/chat or email `support@render.com` if you need help.
|
||||
|
||||
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
125
docs/content/en/hosting-and-deployment/hugo-deploy.md
Normal file
125
docs/content/en/hosting-and-deployment/hugo-deploy.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: Hugo Deploy
|
||||
linktitle: Hugo Deploy
|
||||
description: You can upload your site to GCS, S3, or Azure using the Hugo CLI.
|
||||
date: 2019-05-30
|
||||
publishdate: 2019-05-30
|
||||
lastmod: 2019-05-30
|
||||
categories: [hosting and deployment]
|
||||
keywords: [s3,gcs,azure,hosting,deployment]
|
||||
authors: [Robert van Gent]
|
||||
menu:
|
||||
docs:
|
||||
parent: "hosting-and-deployment"
|
||||
weight: 2
|
||||
weight: 2
|
||||
sections_weight: 2
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
---
|
||||
|
||||
You can use the "hugo deploy" command to upload your site directly to a Google Cloud Storage (GCS) bucket, an AWS S3 bucket, and/or an Azure Storage bucket.
|
||||
|
||||
## Assumptions
|
||||
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You have an account with the service provider ([Google Cloud](https://cloud.google.com/), [AWS](https://aws.amazon.com), or [Azure](https://azure.microsoft.com)) that you want to deploy to.
|
||||
* You have authenticated.
|
||||
* Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login).
|
||||
* AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
|
||||
* Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli).
|
||||
* NOTE: Each service supports alternatives for authentication, including using environment variables. See [here](https://gocloud.dev/howto/blob/#services) for more details.
|
||||
|
||||
## Create a bucket to deploy to
|
||||
|
||||
Create a storage bucket to deploy your site to. If you want your site to be
|
||||
public, be sure to configure the bucket to be publicly readable.
|
||||
|
||||
### Google Cloud Storage (GCS)
|
||||
|
||||
Follow the [GCS instructions for how to create a bucket](https://cloud.google.com/storage/docs/creating-buckets).
|
||||
|
||||
### AWS S3
|
||||
|
||||
Follow the [AWS instructions for how to create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
|
||||
|
||||
### Azure Storage
|
||||
|
||||
Follow the [Azure instructions for how to create a bucket](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal).
|
||||
|
||||
## Configure the deployment
|
||||
|
||||
In the configuration file for your site, add a `[deployment]` section with one
|
||||
or more `[[deployment.targets]]` section, one for each deployment target. Here's
|
||||
a detailed example:
|
||||
|
||||
```
|
||||
[deployment]
|
||||
# By default, files are uploaded in an arbitrary order.
|
||||
# Files that match the regular expressions in the "Order" list
|
||||
# will be uploaded first, in the listed order.
|
||||
order = [".jpg$", ".gif$"]
|
||||
|
||||
|
||||
[[deployment.targets]]
|
||||
# An arbitrary name for this target.
|
||||
name = "mydeployment"
|
||||
# The Go Cloud Development Kit URL to deploy to. Examples:
|
||||
# GCS; see https://gocloud.dev/howto/blob/#gcs
|
||||
# URL = "gs://<Bucket Name>"
|
||||
|
||||
# S3; see https://gocloud.dev/howto/blob/#s3
|
||||
# For S3-compatible endpoints, see https://gocloud.dev/howto/blob/#s3-compatible
|
||||
# URL = "s3://<Bucket Name>?region=<AWS region>"
|
||||
|
||||
# Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure
|
||||
# URL = "azblob://$web"
|
||||
|
||||
# You can use a "prefix=" query parameter to target a subfolder of the bucket:
|
||||
# URL = "gs://<Bucket Name>?prefix=a/subfolder/"
|
||||
|
||||
# If you are using a CloudFront CDN, deploy will invalidate the cache as needed.
|
||||
cloudFrontDistributionID = <ID>
|
||||
|
||||
|
||||
# ... add more [[deployment.targets]] sections ...
|
||||
|
||||
|
||||
# [[deployment.matchers]] configure behavior for files that match the Pattern.
|
||||
# Samples:
|
||||
|
||||
[[deployment.matchers]]
|
||||
# Cache static assets for 20 years.
|
||||
pattern = "^.+\\.(js|css|svg|ttf)$"
|
||||
cacheControl = "max-age=630720000, no-transform, public"
|
||||
gzip = true
|
||||
|
||||
[[deployment.matchers]]
|
||||
pattern = "^.+\\.(png|jpg)$"
|
||||
cacheControl = "max-age=630720000, no-transform, public"
|
||||
gzip = false
|
||||
|
||||
[[deployment.matchers]]
|
||||
pattern = "^.+\\.(html|xml|json)$"
|
||||
gzip = true
|
||||
```
|
||||
|
||||
## Deploy
|
||||
|
||||
To deploy to a target:
|
||||
```
|
||||
hugo deploy [--target=<target name>, defaults to first target]
|
||||
```
|
||||
|
||||
Hugo will identify and apply any local changes that need to be reflected to the
|
||||
remote target. You can use `--dryRun` to see the changes without applying them,
|
||||
or `--confirm` to be prompted before making changes.
|
||||
|
||||
See `hugo help deploy` for more command-line options.
|
||||
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
[Google Cloud]: [https://cloud.google.com]
|
||||
[AWS]: [https://aws.amazon.com]
|
||||
[Azure]: [https://azure.microsoft.com]
|
||||
|
||||
Reference in New Issue
Block a user