mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-17 21:01:26 +02:00
Merge commit '9b0050e9aabe4be65c78ccf292a348f309d50ccd' as 'docs'
``` git subtree add --prefix=docs/ https://github.com/gohugoio/hugoDocs.git master --squash ``` Closes #11925
This commit is contained in:
Bjørn Erik Pedersen
15
docs/content/en/hosting-and-deployment/_index.md
Normal file
15
docs/content/en/hosting-and-deployment/_index.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Hosting and deployment
|
||||
linkTitle: Overview
|
||||
description: Site builds, automated deployments, and popular hosting solutions.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: hosting-and-deployment-overview
|
||||
parent: hosting-and-deployment
|
||||
weight: 1
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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,47 @@
|
||||
---
|
||||
title: Deploy with Rclone
|
||||
description: If you have access to your web host with SFTP/FTP/SSH/HTTP(DAV), you can use rclone to incrementally deploy your entire Hugo website.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [deployment,rclone,sftp]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
aliases: [/tutorials/deployment-with-rclone/]
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
|
||||
* A web host running a web server. This could be a shared hosting environment or a VPS.
|
||||
* Access to your web host with any of the [protocols supported by rclone](https://rclone.org/#providers), such as SFTP.
|
||||
* A functional static website built with Hugo
|
||||
* Deploying from an [Rclone](https://rclone.org) compatible operating system
|
||||
* You have [installed Rclone](https://rclone.org/install/).
|
||||
|
||||
**NB**: You can remove ``--interactive`` in the commands below once you are comfortable with rclone, if you wish. Also, ``--gc`` and ``--minify`` are optional in the ``hugo`` commands below.
|
||||
|
||||
## Getting started
|
||||
|
||||
The spoiler is that you can even deploy your entire website from any compatible OS with no configuration. Using SFTP for example:
|
||||
|
||||
```txt
|
||||
hugo --gc --minify
|
||||
rclone sync --interactive --sftp-host sftp.example.com --sftp-user www-data --sftp-ask-password public/ :sftp:www/
|
||||
```
|
||||
|
||||
## Configure Rclone for even easier usage
|
||||
|
||||
The easiest way is simply to run `rclone config`.
|
||||
|
||||
The [Rclone docs](https://rclone.org/docs/) provide [an example of configuring Rclone to use SFTP](https://rclone.org/sftp/).
|
||||
|
||||
For the next commands, we will assume you configured a remote you named ``hugo-www``
|
||||
|
||||
The above 'spoiler' commands could become:
|
||||
|
||||
```txt
|
||||
hugo --gc --minify
|
||||
rclone sync --interactive public/ hugo-www:www/
|
||||
```
|
||||
|
||||
After you issue the above commands (and respond to any prompts), check your website and you will see that it is deployed.
|
||||
139
docs/content/en/hosting-and-deployment/deployment-with-rsync.md
Normal file
139
docs/content/en/hosting-and-deployment/deployment-with-rsync.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
title: Deploy 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.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [deployment,rsync]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
aliases: [/tutorials/deployment-with-rsync/]
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```txt
|
||||
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 distributions, 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:
|
||||
|
||||
```txt
|
||||
~$ cd && mkdir .ssh & cd .ssh
|
||||
```
|
||||
|
||||
Next, execute this command to generate a new keypair called `rsa_id`:
|
||||
|
||||
```txt
|
||||
~/.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:
|
||||
|
||||
```txt
|
||||
~/.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:
|
||||
|
||||
```txt
|
||||
~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com
|
||||
```
|
||||
|
||||
Now you can easily connect to the remote server:
|
||||
|
||||
```txt
|
||||
~$ 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:
|
||||
|
||||
```txt
|
||||
~/websites/topologix.fr$ editor deploy
|
||||
```
|
||||
|
||||
Add the following content. Replace the `USER`, `HOST`, and `DIR` values with your own values:
|
||||
|
||||
```sh
|
||||
#!/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} # this will delete everything on the server that's not in the local public folder
|
||||
|
||||
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:
|
||||
|
||||
```txt
|
||||
~/websites/topologix.fr$ chmod +x deploy
|
||||
```
|
||||
|
||||
Now you only have to enter the following command to deploy and update your website:
|
||||
|
||||
```txt
|
||||
~/websites/topologix.fr$ ./deploy
|
||||
```
|
||||
|
||||
Your site builds and deploys:
|
||||
|
||||
```txt
|
||||
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 processing tasks into this deployment script as well.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Host on 21YunBox
|
||||
description: Host your Hugo site with 21YunBox's blazing fast Chinese CDN, fully-managed SSL and auto deploys from Gitee.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,21yunbox]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
---
|
||||
|
||||
[21YunBox](https://www.21yunbox.com) is a fully-managed cloud platform dedicated to make web deployment easy within the Chinese Great Firewall where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. It provides blazing fast Chinese CDN, continuous deployment, one-click HTTPS and [other services like managed databases and backend web services](https://www.21yunbox.com/docs/), providing an avenue to launch web projects in China.
|
||||
|
||||
21YunBox includes the following features:
|
||||
|
||||
- Continuous, automatic builds & deploys from GitHub and Gitee
|
||||
- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org)
|
||||
- Instant cache invalidation with a blazing fast, Chinese CDN
|
||||
- Unlimited [custom domains](https://www.21yunbox.com/docs/#/custom-domains)
|
||||
- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites
|
||||
- Native HTTP/2 support
|
||||
- Automatic HTTP → HTTPS redirects
|
||||
- Custom URL redirects and rewrites
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This guide assumes you already have a Hugo project to deploy. If you need a project, use the [Quick Start](/getting-started/quick-start/) to get started or fork 21YunBox's [Hugo Example](https://gitee.com/eryiyunbox-examples/hello-hugo) before continuing.
|
||||
|
||||
## Setup
|
||||
|
||||
You can set up a Hugo site on 21YunBox in two quick steps:
|
||||
|
||||
1. Create a new web service on 21YunBox, and give 21YunBox permission to access your GitHub or Gitee repo.
|
||||
2. Use the following values during creation:
|
||||
|
||||
| Field | Value |
|
||||
| --------------------- | ------------------------------------------------ |
|
||||
| **Environment** | `Static Site` |
|
||||
| **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 21YunBox URL (which looks like `yoursite.21yunbox.com`) as soon as the build is done.
|
||||
|
||||
## Continuous deploys
|
||||
|
||||
Now that 21YunBox is connected to your repo, it will automatically build and publish your site any time you push to GitHub.
|
||||
|
||||
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 21YunBox's [custom domains](https://www.21yunbox.com/docs/#/custom-domains) guide.
|
||||
|
||||
## Support
|
||||
|
||||
Click [here](https://www.21yunbox.com/docs/#/contact) to contact with 21YunBox' experts if you need help.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Host on AWS Amplify
|
||||
description: Develop and deploy a cloud-powered web app with AWS Amplify.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,amplify]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
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/
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Host on Azure Static Web Apps
|
||||
description: Publish a Hugo site to Azure Static Web Apps.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,azure]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
---
|
||||
|
||||
You can create and deploy a Hugo web application to Azure Static Web Apps. The final result is a new Azure Static Web App with associated GitHub Actions that give you control over how the app is built and published. You'll learn how to create a Hugo app, set up an Azure Static Web App and deploy the Hugo app to Azure.
|
||||
|
||||
Here's the tutorial on how to [Publish a Hugo site to Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/publish-hugo).
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Host on Cloudflare Pages
|
||||
description: Cloudflare Pages can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own environment variables.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,cloudflare]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
---
|
||||
|
||||
[Cloudflare Pages](https://developers.cloudflare.com/pages/) are super fast, always up-to-date, and deployed directly from your [Git provider](https://developers.cloudflare.com/pages/get-started/#connect-your-git-provider-to-pages).
|
||||
|
||||
Cloudflare Pages docs have a detailed tutorial on [how to deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/).
|
||||
110
docs/content/en/hosting-and-deployment/hosting-on-firebase.md
Normal file
110
docs/content/en/hosting-and-deployment/hosting-on-firebase.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: 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.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,firebase]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
---
|
||||
|
||||
## 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):
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
firebase login
|
||||
```
|
||||
|
||||
In the root of your Hugo project, initialize the Firebase project with the `firebase init` command:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
## Using Firebase & GitHub CI/CD
|
||||
|
||||
In new versions of Firebase, some other questions apply:
|
||||
|
||||
6. Set up automatic builds and deploys with GitHub?
|
||||
|
||||
Here you will be redirected to login in your GitHub account to get permissions. Confirm.
|
||||
|
||||
7. For which GitHub repository would you like to set up a GitHub workflow? (format: user/repository)
|
||||
|
||||
Include the repository you will use in the format above (Account/Repo)
|
||||
Firebase script with retrieve credentials, create a service account you can later manage in your GitHub settings.
|
||||
|
||||
8. Set up the workflow to run a build script before every deploy?
|
||||
|
||||
Here is your opportunity to include some commands before you run the deploy.
|
||||
|
||||
9. Set up automatic deployment to your site's live channel when a PR is merged?
|
||||
|
||||
You can let in the default option (main)
|
||||
|
||||
After that Firebase has been set in your project with CI/CD. After that run:
|
||||
|
||||
```sh
|
||||
hugo && firebase deploy
|
||||
```
|
||||
|
||||
With this you will have the app initialized manually. After that you can manage and fix your GitHub workflow from: https://github.com/your-account/your-repo/actions
|
||||
|
||||
Don't forget to update your static pages before push!
|
||||
|
||||
## Manual deploy
|
||||
|
||||
To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time:
|
||||
|
||||
```sh
|
||||
hugo && firebase deploy
|
||||
```
|
||||
|
||||
## CI setup (other tools)
|
||||
|
||||
You can generate a deploy token using
|
||||
|
||||
```sh
|
||||
firebase login:ci
|
||||
```
|
||||
|
||||
You can also set up your CI 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:
|
||||
|
||||
```sh
|
||||
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/
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 3.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.7 KiB |
@@ -0,0 +1,190 @@
|
||||
---
|
||||
title: Host on GitHub Pages
|
||||
description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with GitHub Actions
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,github]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. [Create a GitHub account]
|
||||
2. [Install Git]
|
||||
3. [Create a Hugo site] and test it locally with `hugo server`.
|
||||
|
||||
[Create a GitHub account]: https://github.com/signup
|
||||
[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[Create a Hugo site]: /getting-started/quick-start/
|
||||
|
||||
## Types of sites
|
||||
|
||||
There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com.
|
||||
|
||||
{{% note %}}
|
||||
See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
|
||||
|
||||
[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
|
||||
{{% /note %}}
|
||||
|
||||
[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
|
||||
|
||||
## Procedure
|
||||
|
||||
Step 1
|
||||
: Create a GitHub repository.
|
||||
|
||||
Step 2
|
||||
: Push your local repository to GitHub.
|
||||
|
||||
Step 3
|
||||
: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
|
||||
|
||||
|
||||
{style="max-width: 280px"}
|
||||
|
||||
Step 4
|
||||
: Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
|
||||
|
||||
|
||||
{style="max-width: 280px"}
|
||||
|
||||
Step 5
|
||||
: Create an empty file in your local repository.
|
||||
|
||||
```text
|
||||
.github/workflows/hugo.yaml
|
||||
```
|
||||
|
||||
Step 6
|
||||
: Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed.
|
||||
|
||||
{{< code file=.github/workflows/hugo.yaml copy=true >}}
|
||||
# Sample workflow for building and deploying a Hugo site to GitHub Pages
|
||||
name: Deploy Hugo site to Pages
|
||||
|
||||
on:
|
||||
# Runs on pushes targeting the default branch
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
# Allows you to run this workflow manually from the Actions tab
|
||||
workflow_dispatch:
|
||||
|
||||
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
|
||||
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
# Default to bash
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
# Build job
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
HUGO_VERSION: 0.122.0
|
||||
steps:
|
||||
- name: Install Hugo CLI
|
||||
run: |
|
||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||
- name: Install Dart Sass
|
||||
run: sudo snap install dart-sass
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
fetch-depth: 0
|
||||
- name: Setup Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: Install Node.js dependencies
|
||||
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
|
||||
- name: Build with Hugo
|
||||
env:
|
||||
# For maximum backward compatibility with Hugo modules
|
||||
HUGO_ENVIRONMENT: production
|
||||
HUGO_ENV: production
|
||||
run: |
|
||||
hugo \
|
||||
--gc \
|
||||
--minify \
|
||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v2
|
||||
with:
|
||||
path: ./public
|
||||
|
||||
# Deployment job
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v3
|
||||
{{< /code >}}
|
||||
|
||||
Step 7
|
||||
: Commit the change to your local repository with a commit message of something like "Add workflow", and push to GitHub.
|
||||
|
||||
Step 8
|
||||
: From GitHub's main menu, choose **Actions**. You will see something like this:
|
||||
|
||||
|
||||
{style="max-width: 350px"}
|
||||
|
||||
Step 9
|
||||
: When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
|
||||
|
||||
|
||||
{style="max-width: 350px"}
|
||||
|
||||
Step 10
|
||||
: Click on the commit message as shown above. You will see this:
|
||||
|
||||
|
||||
{style="max-width: 611px"}
|
||||
|
||||
Under the deploy step, you will see a link to your live site.
|
||||
|
||||
In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes.
|
||||
|
||||
## Customize the workflow
|
||||
|
||||
The example workflow above includes this step, which typically takes 10‑15 seconds:
|
||||
|
||||
```yaml
|
||||
- name: Install Dart Sass
|
||||
run: sudo snap install dart-sass
|
||||
```
|
||||
|
||||
You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler.
|
||||
|
||||
[Dart Sass]: /hugo-pipes/transpile-sass-to-css/#dart-sass
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [Learn more about GitHub Actions](https://docs.github.com/en/actions)
|
||||
- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
|
||||
- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
|
||||
101
docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
Normal file
101
docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Host on GitLab Pages
|
||||
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.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,gitlab]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
toc: true
|
||||
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 copy=true >}}
|
||||
variables:
|
||||
DART_SASS_VERSION: 1.70.0
|
||||
HUGO_VERSION: 0.122.0
|
||||
NODE_VERSION: 20.x
|
||||
GIT_DEPTH: 0
|
||||
GIT_STRATEGY: clone
|
||||
GIT_SUBMODULE_STRATEGY: recursive
|
||||
TZ: America/Los_Angeles
|
||||
|
||||
image:
|
||||
name: golang:1.20.6-bookworm
|
||||
|
||||
pages:
|
||||
script:
|
||||
# Install brotli
|
||||
- apt-get update
|
||||
- apt-get install -y brotli
|
||||
# Install Dart Sass
|
||||
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
|
||||
- tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
|
||||
- cp -r dart-sass/ /usr/local/bin
|
||||
- rm -rf dart-sass*
|
||||
- export PATH=/usr/local/bin/dart-sass:$PATH
|
||||
# Install Hugo
|
||||
- curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
|
||||
- apt-get install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
|
||||
- rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
|
||||
# Install Node.js
|
||||
- curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION} | bash -
|
||||
- apt-get install -y nodejs
|
||||
# Install Node.js dependencies
|
||||
- "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
|
||||
# Build
|
||||
- hugo --gc --minify
|
||||
# Compress
|
||||
- find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec gzip -f -k {} \;
|
||||
- find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec brotli -f -k {} \;
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
||||
{{% /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.
|
||||
|
||||
```sh
|
||||
# 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/
|
||||
88
docs/content/en/hosting-and-deployment/hosting-on-keycdn.md
Normal file
88
docs/content/en/hosting-and-deployment/hosting-on-keycdn.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Host on KeyCDN
|
||||
description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to set up your static site as a GitLab page behind a KeyCDN pull zone."
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,keycdn]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
---
|
||||
|
||||
[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 log in 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.
|
||||
|
||||
```yml
|
||||
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:
|
||||
|
||||
```sh
|
||||
git remote add origin git@gitlab.com:youruser/ci-example.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/).
|
||||
145
docs/content/en/hosting-and-deployment/hosting-on-netlify.md
Normal file
145
docs/content/en/hosting-and-deployment/hosting-on-netlify.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
title: Host on Netlify
|
||||
description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting,netlify]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
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 sign up 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 want to publish, 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], 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 >}}
|
||||
[context.production.environment]
|
||||
HUGO_VERSION = "0.122.0"
|
||||
{{< /code >}}
|
||||
|
||||
For testing:
|
||||
|
||||
{{< code file=netlify.toml >}}
|
||||
[context.deploy-preview.environment]
|
||||
HUGO_VERSION = "0.122.0"
|
||||
{{< /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`:
|
||||
|
||||
{{< readfile file=netlify.toml highlight=toml >}}
|
||||
|
||||
## 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 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`:
|
||||
|
||||
```txt
|
||||
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:
|
||||
|
||||
```txt
|
||||
cd themes/<theme>
|
||||
git tag
|
||||
# exit with q
|
||||
```
|
||||
|
||||
You can checkout a specific version as follows:
|
||||
|
||||
```txt
|
||||
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:
|
||||
|
||||
```txt
|
||||
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/#build-your-site
|
||||
[site configuration]: /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
|
||||
[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
|
||||
81
docs/content/en/hosting-and-deployment/hosting-on-render.md
Normal file
81
docs/content/en/hosting-and-deployment/hosting-on-render.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Host on Render
|
||||
description: Host your Hugo site for free with Render's global CDN, fully-managed SSL and auto deploys from GitHub.
|
||||
categories: [hosting and deployment]
|
||||
keywords: [hosting]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
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/
|
||||
249
docs/content/en/hosting-and-deployment/hugo-deploy.md
Normal file
249
docs/content/en/hosting-and-deployment/hugo-deploy.md
Normal file
@@ -0,0 +1,249 @@
|
||||
---
|
||||
title: Hugo Deploy
|
||||
description: Upload your site to GCS, S3, or Azure
|
||||
categories: [hosting and deployment]
|
||||
keywords: [deployment,s3,gcs,azure]
|
||||
menu:
|
||||
docs:
|
||||
parent: hosting-and-deployment
|
||||
weight: 20
|
||||
weight: 20
|
||||
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.
|
||||
* You have created a bucket to deploy to. If you want your site to be
|
||||
public, be sure to configure the bucket to be publicly readable as a static website.
|
||||
* Google Cloud: [create a bucket](https://cloud.google.com/storage/docs/creating-buckets) and [host a static website](https://cloud.google.com/storage/docs/hosting-static-website)
|
||||
* Amazon S3: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
|
||||
* Microsoft Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website)
|
||||
|
||||
|
||||
## Configuring your first deployment
|
||||
|
||||
In the configuration file for your site, add a `[deployment]` section
|
||||
and a `[[deployment.targets]]` subsection. The only required parameters are
|
||||
the name and URL:
|
||||
|
||||
```toml
|
||||
[deployment]
|
||||
|
||||
[[deployment.targets]]
|
||||
# An arbitrary name for this target.
|
||||
name = "production"
|
||||
|
||||
# URL specifies the Go Cloud Development Kit URL to deploy to. Examples:
|
||||
URL = "<FILL ME IN>"
|
||||
|
||||
# Google Cloud Storage -- see https://gocloud.dev/howto/blob/#gcs
|
||||
#URL = "gs://<Bucket Name>"
|
||||
|
||||
# Amazon Web Services 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>"
|
||||
|
||||
# Microsoft Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure
|
||||
#URL = "azblob://$web"
|
||||
|
||||
```
|
||||
|
||||
## Deploy
|
||||
|
||||
To deploy to a target:
|
||||
|
||||
```bash
|
||||
hugo deploy [--target=<target name>]
|
||||
```
|
||||
|
||||
The deploy process recursively walks through your local publish directory
|
||||
(`public` by default) and syncs it to the destination bucket, to ensure
|
||||
that the local and remote contents match.
|
||||
|
||||
If you don't specify a target, Hugo will deploy to the first target in your
|
||||
configuration.
|
||||
|
||||
See `hugo help deploy` or [the deploy command-line documentation][commandline] for more command-line options.
|
||||
|
||||
|
||||
### How the file list works
|
||||
|
||||
The first thing `hugo deploy` does is create file lists for local and remote by
|
||||
traversing the local publish directory and remote bucket.
|
||||
|
||||
For both local and remote, the file list includes and excludes files according to
|
||||
the [deployment target's configuration][config] --
|
||||
* If the configuration specifies an `include` pattern, all files
|
||||
are skipped by default except those matching the pattern.
|
||||
* If the configuration specifies an `exclude` pattern, files matching the
|
||||
pattern are skipped.
|
||||
|
||||
|
||||
{{% note %}}
|
||||
When creating the local file list, a few additional skips apply: first, Hugo always
|
||||
skips files named `.DS_Store`.
|
||||
|
||||
Second, Hugo always skips local hidden directories
|
||||
(directories with names starting with a period, e.g. `.git`) and does not
|
||||
traverse into them, except for the special [hidden directory named
|
||||
`.well-known`](https://en.wikipedia.org/wiki/Well-known_URI), which is
|
||||
traversed if it exists.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
|
||||
### How the local and remote file lists are compared
|
||||
|
||||
In the second step, Hugo compares the two file lists to figure out what changes
|
||||
actually need to be made on the remote. File names are compared first; if the
|
||||
local and remote files both exist then the sizes and md5sums are compared. Any
|
||||
difference means that the file will be (re-)uploaded.
|
||||
|
||||
Specifying the `--force` flag will ensure all files are re-uploaded even
|
||||
if Hugo cannot detect any differences between local and remote.
|
||||
|
||||
Files are deleted from the remote bucket if they are not present in the local
|
||||
file list.
|
||||
|
||||
{{% note %}}
|
||||
If a remote file is excluded from the file list generation using the
|
||||
exclude/include configs, then the comparison step will not know to delete the
|
||||
file -- so it will remain on the remote even if it isn't present locally.
|
||||
{{% /note %}}
|
||||
|
||||
If the [`--confirm` or `--dryRun` flags][commandline] are given, Hugo displays
|
||||
what differences it has found and either pauses or stops here.
|
||||
|
||||
### How synchronization works
|
||||
|
||||
Hugo applies the list of changes to the remote storage bucket. Missing and/or
|
||||
changed files are uploaded, and files missing locally but present remotely are
|
||||
deleted. As files are uploaded, their headers are also configured on the remote
|
||||
according to the matchers configuration.
|
||||
|
||||
{{% note %}}
|
||||
As a safety measure to help prevent accidents, if there are more than 256 files
|
||||
to delete, Hugo won't delete any files from the remote. Use the `--maxDeletes`
|
||||
command line flag to override this.
|
||||
{{% /note %}}
|
||||
|
||||
## Advanced configuration
|
||||
|
||||
Here's a full example deployment configuration:
|
||||
|
||||
```toml
|
||||
[deployment]
|
||||
|
||||
# By default, files are uploaded in an arbitrary order.
|
||||
# If you specify an `order` list, files that match regular expressions
|
||||
# in this list will be uploaded first, in the specified order.
|
||||
order = [".jpg$", ".gif$"]
|
||||
|
||||
[[deployment.targets]]
|
||||
# Define one or more targets, e.g., staging and production.
|
||||
# Each target gets its own [[deployment.targets]] section.
|
||||
|
||||
# An arbitrary name for this target.
|
||||
name = "mydeployment"
|
||||
# The Go Cloud Development Kit URL to deploy to. Examples:
|
||||
URL = "<FILL ME IN>"
|
||||
|
||||
# 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 = "<FILL ME IN>"
|
||||
|
||||
# Include or exclude specific files when deploying to this target:
|
||||
# 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.
|
||||
# Note: 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.
|
||||
#
|
||||
# The pattern syntax is documented here: https://godoc.org/github.com/gobwas/glob#Glob
|
||||
# Patterns should be written with forward slashes as separator.
|
||||
#
|
||||
#include = "**.html" # would only include files with ".html" suffix
|
||||
#exclude = "**.{jpg, png}" # would exclude files with ".jpg" or ".png" suffix
|
||||
|
||||
|
||||
#######################
|
||||
[[deployment.matchers]]
|
||||
# Matchers enable special caching, content type and compression behavior for
|
||||
# specified file types. You can include any number of matcher blocks; the first one
|
||||
# matching a given file pattern will be used.
|
||||
|
||||
# See https://golang.org/pkg/regexp/syntax/ for pattern syntax.
|
||||
# Pattern searching is stopped on first match.
|
||||
pattern = "<FILL ME IN>"
|
||||
|
||||
# If true, Hugo will gzip the file before uploading it to the bucket.
|
||||
# With many storage services, this will save on storage and bandwidth costs
|
||||
# for uncompressed file types.
|
||||
#gzip = false
|
||||
|
||||
# If true, Hugo always re-uploads this file even if size and md5 match.
|
||||
# This is useful if Hugo isn't reliably able to determine whether to re-upload
|
||||
# the file on its own.
|
||||
#force = false
|
||||
|
||||
# Content-type header to configure for this file when served.
|
||||
# By default this can be determined from the file extension.
|
||||
#contentType = ""
|
||||
|
||||
# Cache-control header to configure for this file when served.
|
||||
# The default is the empty string.
|
||||
#cacheControl = ""
|
||||
|
||||
# Content-encoding header to configure for this file when served.
|
||||
# By default, if gzip is True, this will be filled with "gzip".
|
||||
#contentEncoding = ""
|
||||
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
[Quick Start]: /getting-started/quick-start/
|
||||
[commandline]: /commands/hugo_deploy/
|
||||
[config]: #advanced-configuration
|
||||
Reference in New Issue
Block a user