diff options
Diffstat (limited to 'docs/content/en/hosting-and-deployment')
11 files changed, 1145 insertions, 0 deletions
diff --git a/docs/content/en/hosting-and-deployment/_index.md b/docs/content/en/hosting-and-deployment/_index.md new file mode 100644 index 000000000..ea9f60f17 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/_index.md @@ -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. diff --git a/docs/content/en/hosting-and-deployment/deployment-with-rsync.md b/docs/content/en/hosting-and-deployment/deployment-with-rsync.md new file mode 100644 index 000000000..ad59b71f1 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/deployment-with-rsync.md @@ -0,0 +1,148 @@ +--- +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 +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 transferring 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 +posts/ +posts/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. diff --git a/docs/content/en/hosting-and-deployment/hosting-on-aws-amplify.md b/docs/content/en/hosting-and-deployment/hosting-on-aws-amplify.md new file mode 100644 index 000000000..34a21e9e9 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-aws-amplify.md @@ -0,0 +1,57 @@ +--- +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. + +## Using a Newer Version of Hugo + +If you need to use a different, perhaps newer, version of Hugo than the version currently supported by AWS Amplify: + +1. Visit the [AWS Amplify Console](https://console.aws.amazon.com/amplify/home), and click the app you would like to modify +1. In the side navigation bar, Under App Settings, click **Build settings** +1. On the Build settings page, near the bottom, there is a section called **Build image settings**. Click **Edit** +1. Under **Live package updates**, click **Add package version override** +1. From the selection, click **Hugo** and ensure the version field says `latest` +1. Click **Save** to save the changes. + + +[Quick Start]: /getting-started/quick-start/ diff --git a/docs/content/en/hosting-and-deployment/hosting-on-bitbucket.md b/docs/content/en/hosting-and-deployment/hosting-on-bitbucket.md new file mode 100644 index 000000000..9ab926751 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-bitbucket.md @@ -0,0 +1,141 @@ +--- +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. + +![Bitbucket Screenshot][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. + +![Bitbucket blog Screenshot][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. diff --git a/docs/content/en/hosting-and-deployment/hosting-on-firebase.md b/docs/content/en/hosting-and-deployment/hosting-on-firebase.md new file mode 100644 index 000000000..3a4039f90 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-firebase.md @@ -0,0 +1,89 @@ +--- +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/ diff --git a/docs/content/en/hosting-and-deployment/hosting-on-github.md b/docs/content/en/hosting-and-deployment/hosting-on-github.md new file mode 100644 index 000000000..ae30ce44a --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-github.md @@ -0,0 +1,116 @@ +--- +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 Github Action Workflow +date: 2014-03-21 +publishdate: 2014-03-21 +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 +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][] and automating development workflows and build with [GitHub Actions]. + +## 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 two 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. + +## Branches for GitHub Actions + +The GitHub Actions used in these instructions pull source content from the `main` branch and then commit the generated content to the `gh-pages` branch. This applies regardless of what type of GitHub Pages you are using. This is a clean setup as your Hugo files are stored in one branch and your generated files are published into a separate branch. + +## GitHub User or Organization Pages + +As mentioned in 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 create a repository named `<USERNAME>.github.io` or `<ORGANIZATION>.github.io` to host your pages +2. By default, content from the `main` branch is used to publish GitHub Pages - rather than the `gh-pages` branch which is the default for project sites. However, the GitHub Actions in these instructions publish to the `gh-pages` branch. Therefore, if you are publishing Github pages for a user or organization, you will need to change the publishing branch to `gh-pages`. See the instructions later in this document. + +## Build Hugo With GitHub Action + +GitHub executes your software development workflows. Everytime you push your code on the Github repository, Github Actions will build the site automatically. + +Create a file in `.github/workflows/gh-pages.yml` containing the following content (based on [actions-hugo](https://github.com/marketplace/actions/hugo-setup)): + +```yml +name: github pages + +on: + push: + branches: + - main # Set a branch to deploy + pull_request: + +jobs: + deploy: + runs-on: ubuntu-20.04 + steps: + - uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes (true OR recursive) + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: 'latest' + # extended: true + + - name: Build + run: hugo --minify + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public +``` + +For more advanced settings [actions-hugo](https://github.com/marketplace/actions/hugo-setup) and [actions-gh-pages](https://github.com/marketplace/actions/github-pages-action). + +## Github pages setting +By default, the GitHub action pushes the generated content to the `gh-pages` branch. This means GitHub has to serve your `gh-pages` branch as a GitHub Pages branch. You can change this setting by going to Settings > GitHub Pages, and change the source branch to `gh-pages`. + +## Change baseURL in config.toml +Don't forget to rename your `baseURL` in `config.toml` with the value `https://<USERNAME>.github.io` for your user repository or `https://<USERNAME>.github.io/<REPOSITORY_NAME>` for a project repository. + +Unless this is present in your `config.toml`, your website won't work. + +## 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 requirement 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/ +[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/#Documentation/git-checkout.txt---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 +[GitHub Actions]: https://docs.github.com/en/actions diff --git a/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md b/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md new file mode 100644 index 000000000..03c7776a7 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md @@ -0,0 +1,86 @@ +--- +title: Host on GitLab +linktitle: Host on GitLab +description: GitLab makes it 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/] +--- + +## 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 + +## BaseURL + +The `baseURL` in your [site configuration](/getting-started/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain. + +## Configure GitLab CI/CD + +Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project. + +{{< code file=".gitlab-ci.yml" >}} +image: registry.gitlab.com/pages/hugo/hugo_extended:latest + +variables: + GIT_SUBMODULE_STRATEGY: recursive + +pages: + script: + - hugo + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +{{< /code >}} + +{{% note %}} +See [this list](https://gitlab.com/pages/hugo/container_registry) if you wish to use a particular Hugo version to build your site. +{{% /note %}} + +## 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. + +```bash +# 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/ diff --git a/docs/content/en/hosting-and-deployment/hosting-on-keycdn.md b/docs/content/en/hosting-and-deployment/hosting-on-keycdn.md new file mode 100644 index 000000000..8d9cb0e63 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-keycdn.md @@ -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 [Zone Alias](https://www.keycdn.com/support/create-a-zone-alias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project. + +Ensure that you use your Zone URL or Zone alias 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 Zone alias / 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/). diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify.md b/docs/content/en/hosting-and-deployment/hosting-on-netlify.md new file mode 100644 index 000000000..1e2da8466 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-netlify.md @@ -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: + +{{< code file="netlify.toml" codeLang="toml" >}} +[context.production.environment] + HUGO_VERSION = "0.83.1" +{{< /code >}} + +For testing: + +{{< code file="netlify.toml" codeLang="toml" >}} +[context.deploy-preview.environment] + HUGO_VERSION = "0.83.1" +{{< /code >}} + +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 diff --git a/docs/content/en/hosting-and-deployment/hosting-on-render.md b/docs/content/en/hosting-and-deployment/hosting-on-render.md new file mode 100644 index 000000000..7a77742e2 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hosting-on-render.md @@ -0,0 +1,92 @@ +--- +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: 2020-01-01 +categories: [hosting and deployment] +keywords: [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](https://render.com/docs/github) and [GitLab](https://render.com/docs/gitlab). +- 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 or GitLab. +* 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 **Static Site** on Render, and give Render permission to access your GitHub/Gitlab repo. +2. Use the following values during creation: + + Field | Value + ------------------- | ------------------- + **Build Command** | `hugo --gc --minify` (or your 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 your GitHub/Gitlab. + +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/ diff --git a/docs/content/en/hosting-and-deployment/hugo-deploy.md b/docs/content/en/hosting-and-deployment/hugo-deploy.md new file mode 100644 index 000000000..da7f77c61 --- /dev/null +++ b/docs/content/en/hosting-and-deployment/hugo-deploy.md @@ -0,0 +1,143 @@ +--- +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: 2021-05-03 +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 container. + +## 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 storage container](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: + +```toml +[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> + +# Optionally, you can include or exclude specific files. +# See https://godoc.org/github.com/gobwas/glob#Glob for the glob pattern syntax. +# If non-empty, the pattern is matched against the local path. +# All paths are matched against in their filepath.ToSlash form. +# If exclude is non-empty, and a local or remote file's path matches it, that file is not synced. +# If include is non-empty, and a local or remote file's path does not match it, that file is not synced. +# As a result, local files that don't pass the include/exclude filters are not uploaded to remote, +# and remote files that don't pass the include/exclude filters are not deleted. +# include = "**.html" # would only include files with ".html" suffix +# exclude = "**.{jpg, png}" # would exclude files with ".jpg" or ".png" suffix + + +# [[deployment.matchers]] configure behavior for files that match the Pattern. +# See https://golang.org/pkg/regexp/syntax/ for pattern syntax. +# Pattern searching is stopped on first match. + +# Samples: + +[[deployment.matchers]] +# Cache static assets for 1 year. +pattern = "^.+\\.(js|css|svg|ttf)$" +cacheControl = "max-age=31536000, no-transform, public" +gzip = true + +[[deployment.matchers]] +pattern = "^.+\\.(png|jpg)$" +cacheControl = "max-age=31536000, no-transform, public" +gzip = false + +[[deployment.matchers]] +# Set custom content type for /sitemap.xml +pattern = "^sitemap\\.xml$" +contentType = "application/xml" +gzip = true + +[[deployment.matchers]] +pattern = "^.+\\.(html|xml|json)$" +gzip = true +``` + +## Deploy + +To deploy to a target: + +```bash +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] + |