Different Docker Tutorial

Unit 2 Chapter 1: Hugo Quick Start

In this chapter, you will use Docker to execute the official Hugo Quick Start exercise for creating a new Hugo app. The official Hugo Quick Start exercise assumes that you're doing your software development in a MacOS host environment. This chapter adapts that exercise to a Docker environment. Also note that this exercise uses the AutoPhugo theme instead of the Ananke theme.

Topics Covered

  • Sharing files between the Docker and host environments
  • Port assignments
  • Viewing apps in the local browser
  • Git submodules

Ownership By Root

Please note that the Hugo app you create will be owned by root in not only the Docker environment but in your host environment as well. While it's easy to change ownership of files from root to that of your regular username, I disagree with this practice and will show you my way of doing things in later chapters.

Starting the Docker Container

  • In a shell terminal, enter the following commands:
cd
mkdir -p docker-hugo
cd docker-hugo
  • Enter the following command to start up and enter a new Docker container:
docker run -i -t --rm -p 1313:1313 -w /myapp -v ${PWD}:/myapp debian:bullseye bash
  • Note that the "-p 1313/1313" part of the above command specifies that port 1313 in the Docker container correspond to port 1313 in the host environment. This will be important when it's time to view your Hugo app in your web browser.
  • Note that the "-w /myapp" part of the above command specifies the /myapp directory as the working directory. When you start up the Docker container, you end up in the working directory by default.
  • Note that the "-v ${PWD}:/myapp" establishes file sharing. The present working directory in your host OS corresponds to the /myapp directory in the Docker container. Any file created in one of these two directories is automatically created in the other. Any file edited in one of these directories is automatically edited in the other. Any file deleted in one of these directories is automatically deleted in the other.
  • After the Docker container is built, the screen output should look something like this:
Unable to find image 'debian:bullseye' locally
bullseye: Pulling from library/debian
07f1101e3e85: Pull complete 
Digest: sha256:ed24765036a205a9715179c9bfa6af01df380d3cce174d9ee2a0852724567edc
Status: Downloaded newer image for debian:bullseye
  • You should now be in the Docker container. The prompt should look something like this:
root@e6688fa1310a:/myapp#
  • Open a new shell terminal tab for entering commands in your host environment.
  • In this host shell terminal tab, enter the docker ps -a to list the Docker containers. The screen output should look something like this:
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                    NAMES
e6688fa1310a        debian:bullseye     "bash"              43 seconds ago      Up 42 seconds       0.0.0.0:1313->1313/tcp   zen_shockley
  • Enter the command docker images -a to list the Docker images. The screen output should look something like this:
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
debian              bullseye            546a93a8e0a6        3 days ago          117MB

Installing Hugo

  • Return to the Docker terminal tab, and enter the following command to update the software package list:
apt-get update
  • After the software package list is updated, enter the following command in the Docker container to install Git and Hugo:
apt-get install -y git hugo

Creating the New Hugo App

  • In the Docker container, enter the following command:
hugo new site quickstart
  • Congratulations! Your new Hugo app has been created virtually instantaneously. The screen output should look something like this:
Congratulations! Your new Hugo site is created in /myapp/quickstart.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/, or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.
  • In the Docker container, enter the command ls. You should now see the new "quickstart" app.
  • Go to the host shell terminal tab, and enter the command "ls". You should now see your new "quickstart" app here as well. This shows that the file sharing is working.
  • In your host system, open the file manager and go to the docker-hugo directory you created earlier in this chapter. You should now see the "quickstart" app within it. Again, this shows that the file sharing is working.
  • In the file manager, enter the "quickstart" directory. Now you should see the files within the app.

Viewing the Blank Hugo App

  • In the Docker container, enter the following commands:
cd quickstart
hugo server -D --bind=0.0.0.0
  • The "hugo server" command starts up the Hugo server. The "--bind=0.0.0.0" part specifies the use of IP address 0.0.0.0 for the Docker environment, which corresponds to localhost in the host environment.
  • Open your web browser, and go to the URL http://localhost:1313/ on your host system. There should be a blank screen but no error message. Your app is there, but there's no content whatsoever.
  • In the Docker container, press Ctrl-C to stop the Hugo server when you're ready to move on.

Adding A Hugo Theme

  • Start a new Git repository. (Unlike some other web frameworks, Hugo does not automatically make a new app a Git repository.) Enter the following command in the Docker container:
git init
  • Hugo themes involve Git submodules. A Git submodule is a pre-existing upstream Git repository used in your project. The .gitmodules file stores this upstream's project remote URL on the web and its location within your project. When this sub-project is changed, it's easy to update its code within your project.
  • Now it's time to add the AutoPhugo theme to your app by providing the above .gitmodules file and downloading the AutoPhugo source code to the themes directory in your project. Enter the following command to do this:
git submodule add https://github.com/kc0bfv/autophugo.git themes/autophugo
  • Initialize your local configuration file by entering the following command:
git submodule init
  • Enter the following command:
git submodule update
  • Configure your app to use the AutoPhugo theme by entering the following commands:
cp themes/autophugo/exampleSite/config.toml . # Get the configuration file
echo 'theme = "autophugo"' >> config.toml # Specify the AutoPhugo theme
cp -R themes/autophugo/exampleSite/content . # Copy the initial content pages from AutoPhugo to your app
cp -R themes/autophugo/exampleSite/assets . # Copy the initial image files from AutoPhugo to your app
  • Enter the command hugo server -D --bind=0.0.0.0.
  • Open your web browser, and go to the URL http://localhost:1313/ on your host system. Now you should see the AutoPhugo app, including the cute animal pictures. MEOW! PURR! WOOF! (Insert sound of fish here.)
  • When you're ready to move on, go back to the Docker container and press Ctrl-C to stop the Hugo server.

Deleting the App

  • No, you CANNOT delete this app from your host system as your regular username, because this app is owned by root. The easiest way to delete this app is by going into your Docker container and following the steps below:
  • In the Docker container, enter the command cd ...
  • Enter the command ls. You should now see the quickstart directory.
  • Enter the command rm -r quickstart. This deletes the quickstart app.
  • Enter the command "ls" in the Docker container. The quickstart app should be gone.
  • Enter the command "ls" from the host system terminal tab. The quickstart app should be gone.
  • Go to the file manager window. The quickstart app in the "docker-hugo" directory should be gone.

Cleaning Up Docker

  • In your Docker container, enter the command exit to return to the host system.
  • To delete all Docker networks, enter the command docker network prune -f.
  • To view the list of Docker containers, enter the command docker ps -a.
  • To delete all of these Docker containers, enter the following commands:
for i in $(docker ps -a -q)
do
  docker kill $i; wait;
  docker rm -f $i; wait;
done;
  • To view the list of Docker containers, enter the command docker ps -a. This list should now be empty.
  • To view the list of Docker images, enter the command docker images -a.
  • To delete all of these Docker images, enter the following commands:
for i in $(docker images -a -q)
do
  docker kill $i; wait;
  docker rmi -f $i; wait;
done;
  • To view the list of Docker images, enter the command docker images -a. This list should now be empty.
← Unit 2 IntroductionChapter 2: Hugo Neutrino →