diff options
Diffstat (limited to 'content/posts')
| -rw-r--r-- | content/posts/007.md | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/content/posts/007.md b/content/posts/007.md new file mode 100644 index 0000000..5382f4d --- /dev/null +++ b/content/posts/007.md @@ -0,0 +1,171 @@ +--- +title: Building a Static Site with Hugo and Docker +tags: posts +--- + +This will be a quick walkthrough of how to create a static site using Hugo, and use Nginx to serve it. + +**Prerequisites** + +| **Skill** | **Description** | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Basic Terminal Usage** | Familiarity with navigating directories and running basic commands in a terminal. | +| **Git** | Ability to initialize a Git repository, commit changes, and interact with remote repositories. | +| **Markdown** | Knowledge of writing basic content in Markdown format (used for posts). | +| **Docker Basics** | Understanding of Docker commands for building images and running containers. | +| **HTML/CSS Basics** | General awareness of HTML and CSS for customising static site content.<br> | +| Go | Go should be installed on your system to use Hugo with the `go install` method. Alternatively, you can download Hugo binaries directly or use a package manager. | +# Step 1: Installing Hugo + +Hugo is a static site generator, meaning it builds HTML, CSS, and JavaScript that doesn't need a backend server, since the website's content is static. + +You can install Hugo in multiple ways. If you already have Go installed, you can use + +```shell +go install github.com/gohugoio/hugo@latest +``` + +Alternatively, you can install Hugo following the [official install guide](https://gohugo.io/installation/)> + +# Step 2: Creating a New Hugo Site +To create a new Hugo site, run: + +```shell +hugo new site website +``` +This creates a new folder called `website` with the basic structure of a Hugo site. + +# Step 3: Setting Up a Theme +By default, Hugo doesn't ship with any themes installed, so its likely you'll want to add one. A list of pre-made themes exist [here](https://themes.gohugo.io/), which saves you from having to create one from scratch. Typically, this involves using a Git submodule to manage the theme: + +```shell +cd website +git init +git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod +``` + +A Git submodule is a way to link a separate repository (the theme) into your project without copying it directly. This keeps the theme up-to-date and lets you manage it separately from your main website's content. + + +To use the theme, add it to your `config.toml` file: +```shell +echo 'theme = ["PaperMod"]' >> hugo.toml +``` + +Alternatively, you could manually download the theme and place it in the `themes` folder, but using submodules allows for easier updates. + +# Step 4: Personalising Your Site +Open `config.toml` in your favorite code editor (e.g., VS Code), and change the `title` line to peronsalise your site's name: + +```toml +`title = "<insert name>'s blog"` +``` +This will update the title of your site, which you’ll see when we generate the site in a moment. + +# Step 5: Creating a New Post +To create a new post, run the following command: +```shell +hugo new content content/posts/my-first-post.md +``` + +This will create a new file in the `content/posts` directory, named `my-first-post.md`. When you open it, you’ll see: +```markdown ++++ +title = 'My First Post' +date = 2024-09-08T15:44:30+01:00 +draft = true ++++ +``` +The block of text wrapped in `+++` is called "front matter" and acts as metadata for your post. It won't be visible in your generated website, the actual content of your post goes below this. + +Now, you can edit the file to include your first post: +```markdown ++++ +title = 'My First Post' +date = 2024-09-08T15:44:30+01:00 +draft = true ++++ +## Welcome! + +This is my first post on my new site. It's written in markdown and utilises hugo for generating html which browsers understand and can parse. + +Visit the [Hugo](https://gohugo.io) website! +``` + +# Step 6: Previewing Your Website +To preview your website locally, run the following command: +```shell +hugo server --buildDrafts +``` + +This will start a local server, and you can view your site by visiting `http://localhost:1313` in your browser. + +# Step 7: Publishing the Website +Once you're ready to publish, update your post by changing `draft = true` to `draft = false` (or just delete the `draft` property) and run: + +```shell +hugo +``` + +This will build your site and place the generated files in the `public` folder. This folder contains all the HTML, CSS, and JavaScript that make up your static site. + +From here you can deploy it following [Hugo's own guide](https://gohugo.io/categories/hosting-and-deployment/. However, most of these options involve using someone else's compute, and our goal here is self hosting. +# Step 8: Dockerising your Site +Now that you have a static site in the `public` folder, let's create a Docker image that will serve your site using Nginx, a lightweight web server. While you could install Nginx directly on a server and follow [this guide](https://gohugo.io/hosting-and-deployment/deployment-with-rclone/) to deploy your site, using Docker offers several advantages. Containers provide a reproducible, isolated environment that makes it easy to package, run, and deploy your site across different systems. So, let's use Docker to handle serving your site instead. + +Create a `Dockerfile` with the following content +```dockerfile +FROM nginx:1.27.1 +COPY public /usr/share/nginx/html +``` +This tells Docker to use the official Nginx image and copy the files from your `public` folder (which Hugo generated) into the default location that Nginx serves from. + +# Step 9: Building and Running the Docker Image +To proceed, you'll need a container registry. We'll use Docker hub for this example (you'll need an account) but you can use whatever container registry you have access to. + +To build your Docker image, run: +```shell +docker build . -t <dockerusername>website:0.0.1 +``` +Here: +- `-t <dockerusername>website:0.0.1` tags the image with a name (`<dockerusername/website`) and a version (`0.0.1`), which will be important later when you want to publish it. +- the `.` tells Docker to build the image from the current directory (which contains your `Dockerfile` and `public` folder). + +Now that you have the Docker image locally, you can run it using +```shell +docker run -p 8080:80 <dockerusername>website:0.0.1 +``` + +Here, `-p 8080:80` maps port 8080 on your local machine to port 80 in the Docker container, where Nginx serves the content. + +Now, open a browser and go to `http://localhost:8080`. You should see your static site served by Nginx! + +But your server is not your local machine (potentially), so you need a method of getting the image from your local machine, to your server. We can use container registries as an intermediary. + +1. First login to Docker Hub: +```shell +docker login +``` +2. Push your image to Docker Hub, by default this image will be public. +```shell +`docker push <dockerusername>website:0.0.1 +``` +3. SSH into the server +```shell +ssh user@server-ip +``` +4. Pull the Image (we don't need to login since the image is public): +```shell +docker <dockerusername>website:0.0.1 +``` +5. Run the Docker Image +```shell +docker run -d -p 80:80 <dockerusername>website:0.0.1 +``` +- `-d` runs the container in detached mode (in the background). +- `-p 80:80` maps port 80 of the container (where Nginx is running) to port 80 on the server, making the website accessible via the server's IP address in a browser. + +You will be able to access the website by visiting `http://server-ip:80` + +# Conclusion +Congratulations on creating and running your first static website with Hugo and Docker!
\ No newline at end of file |