Information Technology Grimoire

Version .0.0.1

IT Notes from various projects because I forget, and hopefully they help you too.

Hugo Github Netlify Checklist

This check list is for a single worker on a single machine. Multiple workers/multiple locations all editing the same git account require different instructions to work together, mostly as it relates to using git.

Time Expectations

Initial Setup/Prerequisites

The intial setup process takes about 30 minutes to 60 minutes depending on how fast you read and click the buttons, setup accounts, etc

The first setup, account creation, etc is what consumes the most time.

Setup the following accounts:

  • Cloudflare Cloudflare manges DNS
  • GitHub Stores your static files and hugo build
  • Netlify Serves content from github to their CDN

Install the following software (or equivalent for your OS):

  • SSH or Terminal to generate SSH keys, but also be done in git bash.
  • Go Lang Go is a requirement for Hugo
  • Hugo Hugo is the static site generator

Other/Additional Sites

Subsequent sites take 15 minutes or less to setup and deploy if you are fluid with the process and have accounts created. A single github/netlify account can have many domains attached. All of your accounts will be setup already, so you will only need to add a site configuration, and this is fast. You will not need to setup everything again, only add an additional config once for each site.

For example if you want an additional site and additional sub or main domain, you would create a new site in netlify, and link it to a new repo in github. You would init that new repo on your local pc in a new folder, different for each site.

You can have something like: info.yoursite.com and yoursite.com and they would be separate projects.

When you run hugo locally, you run it from the site folder you created for each site.

Work Flow

To understand how you will edit/add pages, review this work flow. This is your regular, repeated editing task to create content:

  • Edit markdown by creating an _index.md file in a folder for each category
  • Edit markdown by creating something.markdown for each topic in that category
  • Edit images and store them in static/i/ link to them as /i/ in your markdown
  • Add files to staging: git add .
  • Commit work to your local git staging: git commit -m "some comment"
  • Push work to github then wait 45 seconds, done a few times per day git push

It takes only a few minutes per peice of content once you get in the groove.

DOMAIN NAME PURCHASE

You can use a free netlify app name, or a full domain name of your own, or a subdomain that you control. This is a $11 a year fee from cloudflare, but it’s worth having your own domain name. You can also skip this and do it free if you use the netlify.app domain.

  • Purchase domain from cloudflare Cloudflare. It is $11 approx and there are no hidden fees. Don’t use namecheap or route53 or anything else.

Create SSH Keys

On your local machine, you will need an ssh key. Using git bash or whatever your preferred git client is that supports key generation: ssh-keygen -t ed25519 -C "your_email@example.com"

You will need the files that are created in the ~/.ssh/ for the next step.

You can see your public key by looking at the following location on windows, if you are using Terminal as your ssh keygen:

type %USERPROFILE%\.ssh\id_ed25519.pub

This is the information that github will need next.

GITHUB SETUP

If you intend to use github for revision control and automated publishing from github to netlify, you will need a github account. Make a repo (it can be public or private), so you can connect this repo with netlify. The free tier is generous and likely adequate for anyone reading this.

Once you have authorized ssh keys, you do not need to authorize them again. All future repos and projects will know how to use them. If you work from multiple computers, you will need to use multiple keys.

HUGO Setup

Hugo generates the static site from your markdown text. You’ll have files in a directory called “content” when it’s running and this will be your “working” site. The production site will be on netlify CDN. You edit your files and view the changes locally, on your machine using hugo’s single binary as a temporary server.

When you upload your working files to github, netlify will notice the change and then publish to the CDN.

Hugo Installation

You only need to install hugo once, but you create a new project for every site. You can link a different project to a different repo and host many websites this way.

Create Hugo Project

hugo new site something
cd something

GIT INIT

In order for git to begin tracking your work and page changes, you need to initialize the local copy and connect it to github repo you created earlier

You are in the something directory you created previously when running the git init commands.

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:yourgithubaccount/your-repo-here.git
git remote set-url origin git@github.com:yourgithubaccount/your-repo-here.git
git push -u origin main

You only do this once, the first time. Afterwards you will use:

git add .
git commit -m "bleh bleh some description"
git push

Hugo Theme

If using the hugo theme techdoc (this site):

1. Add Theme as Submodule

We needed to init before we can add a submodule, that is why things are in this order. This is the very basic, no data, view your working theme step.

git submodule add https://github.com/thingsym/hugo-theme-techdoc.git themes/hugo-theme-techdoc

Initialize and update submodules

git submodule update --init --recursive

Modify your config.toml or hugo.toml to include the theme (theme = ‘hugo-theme-techdoc’)

If using the hugo-them-techdoc you will need to use the linked config.toml and delete the hugo.toml.

Start Hugo Working Server

hugo server --noHTTPCache --disableFastRender --port=1313

Browse to to Local Copy

Your local server, that will update as you edit markdown files is located at the following URL: http://localhost:1313

Note, you MUST have a config.toml for it to build properly on github. Delete the hugo.toml and use the config.toml I linked as an example.

You might need to stop and restart the local hugo server if you modify the toml files.

NETLIFY SETUP

Netlify does automated builds and allows you to utlize github as part of your CI/CD pipeline. It will grab content from github and push it to it’s free CDN. The free tier is very generous and the paid tier is also generous.

You do not have any content yet, but you will connect netlify to github now so that when you push to github, it will appear in netlify CDN.

Create Netlify Account

Setup Netlify Project

  • Create Netlify Project to get Project Name (something.netlify.app)

Connect Netlify to Github

  • Link Netlify account with your GitHub account

Configure Netlify Build Settings

Site Configuraiton > Continuous deployment > Build Command: hugo --gc --minify -b $URL

Configure Netlify Build Environment

  • Verify hugo version with: hugo version
  • Copy the version string (0.123.4)
  • Setup a new Environment variable in your Site Configuration

Site Configuration > Environment Variables > Add Variable: HUGO_VERSION

Set it to be whatever the hugo version was when you checked on your local pc (0.123.4) or some string like that.

It will create several contexts (Prod, Reviews Branch, Netlify CLI), they should all be whatever your hugo version string said.

Do Initial Netlify Deploy

Deploys > Trigger Deploy |

Review logs for success/failure. Troubleshoot build settings if required. View on your https://something.netlify.app project domain. If it looks good, then you can configure DNS. If not, troubleshoot.

NETLIFY CUSTOM DOMAIN

You will use the netlify.app project name you made and create either a CNAME or A record depending on if you have a root domain or a subdomain you are connecting to netlify

Configure Domain

  • Use Cloudflare to manage your DNS records
  • Wait for DNS changes to propagate (can take up to 48 hours)
  • Verify DNS configuration using a DNS lookup tool such as DNS Checker

Add Custom Domain

Use grimoire.jamesfraze.com as an example (it’s a subdomain, so using CNAME). Add the custom domain in Netlify under “Domain settings”

  • IF Subdomain: Site > DNS > Records > Add Record > CNAME whatever (pointed to the something.netlify.app)
  • IF full domain: Site > DNS > Records > Add Record > A pointing to Netlify’s IP address

I do not know Netlify’s current ip for the global load balancer. As of the time of writing, this is the information I had:

Netlify IP Docs

https://www.netify.ai/resources/ips/99.83.190.102 https://www.netify.ai/resources/ips/75.2.60.5

NORMAL WORKFLOW (WORKING)

You now have a working site and the the connections should be all setup. You will edit files in the “content” directory and then push to git.

You run all of these commands from the root of your hugo site, ie something that we created above

Start Hugo in Other Terminal

hugo server --noHTTPCache --disableFastRender --port=1313`

Monitor in Local Browser

http://localhost:1313

Create Markdown Content

Git Workflow (Editing)

git add .
git commit -m "something"

Keep adding and committing as often as you like. Each commit is a restore point of the changes you’ve done, so make your comments meaningful. I might commit 50+ more times a day depending on how much work I’m doing. If you do not commit, then you do not have a restore point.

Git Workflow (Publishing)

When you are ready to publish to github and then have your data built and set out to netlify just push to github from your root directory. I typically only do this a few times a day.

git push

Final Steps

Verify Live Changes

Review your full domain and after about 30 seconds you should see your changes.

  • Verify deployment in Netlify |
  • Review your live, public site at it’s public domain |

Fine Tune

You should probably learn about short codes, partials, editing the theme, about now.

  • Enable HTTPS by setting up an SSL/TLS certificate through Netlify (Site > Domain Management > HTTPS)
  • Ensure certificate renewal is automated
  • Perform a final site check (links, content, functionality)
  • Update any environment variables if needed in netlify build and local config.toml
  • Utilize any hugo short codes as required
  • Utilize any hugo partials as required
  • Customize your site using hugo custom css as required
  • Confirm the site is live and operational and keep adding content