diff options
Diffstat (limited to 'content/posts/2024-09-08-01.md')
| -rw-r--r-- | content/posts/2024-09-08-01.md | 173 |
1 files changed, 0 insertions, 173 deletions
diff --git a/content/posts/2024-09-08-01.md b/content/posts/2024-09-08-01.md deleted file mode 100644 index 39d1f70..0000000 --- a/content/posts/2024-09-08-01.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Building a Static Site with Hugo and Docker -tags: posts -toc: true ---- - -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 |