docs: create a guide about building a Docker image

exampleSite/content/docs/deployment/docker/index.md

@@ -0,0 +1,93 @@
++++
+# type = "docs"
+title = "Building a Docker Image"
+linkTitle = "Docker"
+date = 2022-07-13T10:30:29+08:00
+# description = "" # Used by description meta tag, summary will be used instead if not set or empty.
+featured = false
+draft = false
+comment = true
+toc = true
+reward = true
+pinned = false
+carousel = false
+categories = ["Deployment"]
+tags = ["Docker", "Nginx"]
+series = ["Docs"]
+images = []
++++
+
+This article will detail how to build a Docker images.
+
+<!--more-->
+
+## Principle
+
+1. Use Hugo to build the site and generate static files.
+1. Use Nginx as the server to handle requests.
+
+## Dockerfile
+
+Create a `Dockerfile` in the site root.
+
+```docker {title="Dockerfile"}
+{{% code/deployment-docker-dockerfile %}}
+```
+
+- There are two stages to the build, a build stafe and a release stage. The release stage contains only the generated static files, keeping the size of the Docker image as small as possible.
+- If you have `defaultContentLanguageInSubdir` enabled, please uncomment and modify it on demand.
+- The `HUGO_BASEURL` parameter is used to specify the `baseURL` of the site during the build, and is generally used when the `baseURL` is different from the configuration, so you can remove it yourself if you don't need it.
+- `HUGO_MODULE_PROXY` and `NPM_CONFIG_REGISTRY` are optional build parameters that can be removed if not needed.
+
+## Nginx
+
+Create a `deploy/nginx/default.conf` in the site root:
+
+```nginx {title="deploy/nginx/default.conf"}
+{{% code/deployment-docker-nginx %}}
+```
+
+## Build
+
+```bash
+{{% code/deployment-docker-build %}}
+```
+
+- `mysite`: the image name.
+- `HUGO_BASEURL`：the `baseURL`.
+
+For users located in China mainland, you need to specify `HUGO_MODULE_PROXY` and `NPM_CONFIG_REGISTRY` to build the mirror successfully and quickly:
+
+```bash
+{{% code/deployment-docker-build-china %}}
+```
+
+## Deployment
+
+There are many ways to deploy Docker, such as `docker run`, `k8s`, etc. This article will only explain `docker run`.
+
+### Run
+
+```bash
+{{% code/deployment-docker-run %}}
+```
+
+> For local testing, you need to change the `baseURL` parameter or the `HUGO_BASEURL` build parameter, e.g. `http://localhost:2333`.
+
+### Stop
+
+```bash
+{{% code/deployment-docker-stop %}}
+```
+
+### Start
+
+```bash
+{{% code/deployment-docker-start %}}
+```
+
+### Remove
+
+```bash
+{{% code/deployment-docker-remove %}}
+```

exampleSite/content/docs/deployment/docker/index.zh-cn.md

@@ -0,0 +1,93 @@
++++
+# type = "docs"
+title = "构建 Docker 镜像"
+linkTitle = "Docker"
+date = 2022-07-13T10:30:29+08:00
+# description = "" # Used by description meta tag, summary will be used instead if not set or empty.
+featured = false
+draft = false
+comment = true
+toc = true
+reward = true
+pinned = false
+carousel = false
+categories = ["部署"]
+tags = ["Docker", "Nginx"]
+series = ["文档"]
+images = []
++++
+
+本文将详细介绍如何构建 Docker 镜像。
+
+<!--more-->
+
+## 原理
+
+1. 使用 Hugo 构建站点，生成静态文件。
+1. 使用 Nginx 作为服务器，处理请求。
+
+## Dockerfile
+
+于根目录创建 `Dockerfile`：
+
+```docker {title="Dockerfile"}
+{{% code/deployment-docker-dockerfile %}}
+```
+
+- 构建一共有两个阶段，一个构建阶段，一个发布阶段。发布阶段仅包含生成的静态文件，尽可能地降低 Docker 镜像大小。
+- 如果你开启了 `defaultContentLanguageInSubdir`，请取消对应的注释和按需修改。
+- `HUGO_BASEURL` 参数用于构建期间指定站点的 `baseURL`，一般用于 `baseURL` 不同于配置的情况，如果不需要可以自行删除。
+- `HUGO_MODULE_PROXY` 和 `NPM_CONFIG_REGISTRY` 都是可选的构建参数，不需要可以自行删除。
+
+## Nginx
+
+于根目录创建 `deploy/nginx/default.conf`：
+
+```nginx {title="deploy/nginx/default.conf"}
+{{% code/deployment-docker-nginx %}}
+```
+
+## 构建
+
+```bash
+{{% code/deployment-docker-build %}}
+```
+
+- `mysite`：镜像名称。
+- `HUGO_BASEURL`：`baseURL`。
+
+对于位于中国大陆的用户，需要指定 `HUGO_MODULE_PROXY` 和 `NPM_CONFIG_REGISTRY`，以便成功和快速地构建镜像:
+
+```bash
+{{% code/deployment-docker-build-china %}}
+```
+
+## 部署
+
+Docker 部署方式很多，如 `docker run`，`k8s` 等等，本文仅对 `docker run` 进行说明。
+
+### 创建并启动
+
+```bash
+{{% code/deployment-docker-run %}}
+```
+
+> 本地测试时，需要修改 `baseURL` 参数或者 `HUGO_BASEURL` 构建参数，如：`http://localhost:2333`。
+
+### 停止
+
+```bash
+{{% code/deployment-docker-stop %}}
+```
+
+### 启动
+
+```bash
+{{% code/deployment-docker-start %}}
+```
+
+### 删除
+
+```bash
+{{% code/deployment-docker-remove %}}
+```

exampleSite/content/docs/deployment/docker/index.zh-tw.md

@@ -0,0 +1,93 @@
++++
+# type = "docs"
+title = "構建 Docker 鏡像"
+linkTitle = "Docker"
+date = 2022-07-13T10:30:29+08:00
+# description = "" # Used by description meta tag, summary will be used instead if not set or empty.
+featured = false
+draft = false
+comment = true
+toc = true
+reward = true
+pinned = false
+carousel = false
+categories = ["部署"]
+tags = ["Docker", "Nginx"]
+series = ["文檔"]
+images = []
++++
+
+本文將詳細介紹如何構建 Docker 鏡像。
+
+<!--more-->
+
+## 原理
+
+1. 使用 Hugo 構建站點，生成靜態文件。
+1. 使用 Nginx 作為服務器，處理請求。
+
+## Dockerfile
+
+於根目錄創建 `Dockerfile`：
+
+```docker {title="Dockerfile"}
+{{% code/deployment-docker-dockerfile %}}
+```
+
+- 構建一共有兩個階段，一個構建階段，一個發布階段。發布階段僅包含生成的靜態文件，盡可能地降低 Docker 鏡像大小。
+- 如果你開啟了 `defaultContentLanguageInSubdir`，請取消對應的註釋和按需修改。
+- `HUGO_BASEURL` 參數用於構建期間指定站點的 `baseURL`，一般用於 `baseURL` 不同於配置的情況，如果不需要可以自行刪除。
+- `HUGO_MODULE_PROXY` 和 `NPM_CONFIG_REGISTRY` 都是可選的構建參數，不需要可以自行刪除。
+
+## Nginx
+
+於根目錄創建 `deploy/nginx/default.conf`：
+
+```nginx {title="deploy/nginx/default.conf"}
+{{% code/deployment-docker-nginx %}}
+```
+
+## 構建
+
+```bash
+{{% code/deployment-docker-build %}}
+```
+
+- `mysite`：鏡像名稱。
+- `HUGO_BASEURL`：`baseURL`。
+
+對於位於中國大陸的用戶，需要指定 `HUGO_MODULE_PROXY` 和 `NPM_CONFIG_REGISTRY`，以便成功和快速地構建鏡像:
+
+```bash
+{{% code/deployment-docker-build-china %}}
+```
+
+## 部署
+
+Docker 部署方式很多，如 `docker run`，`k8s` 等等，本文僅對 `docker run` 進行說明。
+
+### 創建並啟動
+
+```bash
+{{% code/deployment-docker-run %}}
+```
+
+> 本地測試時，需要修改 `baseURL` 參數或者 `HUGO_BASEURL` 構建參數，如：`http://localhost:2333`。
+
+### 停止
+
+```bash
+{{% code/deployment-docker-stop %}}
+```
+
+### 啟動
+
+```bash
+{{% code/deployment-docker-start %}}
+```
+
+### 刪除
+
+```bash
+{{% code/deployment-docker-remove %}}
+```

exampleSite/layouts/shortcodes/code/deployment-docker-build-china.html

@@ -0,0 +1,5 @@
+$ docker build -t mysite \
+  --build-arg HUGO_BASEURL=https://example.com \
+  --build-arg HUGO_MODULE_PROXY=https://goproxy.cn \
+  --build-arg NPM_CONFIG_REGISTRY=https://registry.npmmirror.com \
+  .

exampleSite/layouts/shortcodes/code/deployment-docker-build.html

@@ -0,0 +1,3 @@
+$ docker build -t mysite \
+  --build-arg HUGO_BASEURL=https://example.com \
+  .

exampleSite/layouts/shortcodes/code/deployment-docker-dockerfile.html

@@ -0,0 +1,39 @@
+###############
+# Build Stage #
+###############
+FROM klakegg/hugo:ext-ubuntu as builder
+
+WORKDIR /src
+COPY . /src
+
+ARG HUGO_ENV=production
+ENV HUGO_ENV=${HUGO_ENV}
+
+# Base URL
+ARG HUGO_BASEURL=/
+ENV HUGO_BASEURL=${HUGO_BASEURL}
+
+# Module Proxy
+ARG HUGO_MODULE_PROXY=
+ENV HUGO_MODULE_PROXY=${HUGO_MODULE_PROXY}
+
+# NPM mirrors, such as https://registry.npmmirror.com
+ARG NPM_CONFIG_REGISTRY=
+ENV NPM_CONFIG_REGISTRY=${NPM_CONFIG_REGISTRY}
+
+# Install dependencies
+RUN npm install
+RUN npm install -g @fullhuman/postcss-purgecss rtlcss
+
+# Build site
+RUN hugo --minify --gc --enableGitInfo
+
+# Set the fallback 404 page if defaultContentLanguageInSubdir is enabled, please replace the `en` with your default language code.
+# RUN cp ./public/en/404.html ./public/404.html
+
+###############
+# Final Stage #
+###############
+FROM nginx
+COPY --from=builder /src/public /app
+COPY deploy/nginx/default.conf /etc/nginx/conf.d/default.conf

exampleSite/layouts/shortcodes/code/deployment-docker-nginx.html

@@ -0,0 +1,21 @@
+server {
+    listen       80;
+    listen  [::]:80;
+    server_name  localhost;
+
+    root   /app;
+
+    location / {
+        index  index.html index.htm;
+    }
+
+    location ~* ^/([^/]+) {
+        index  index.html index.htm;
+        error_page 404 = @error;
+    }
+
+    error_page 404 /404.html;
+    location @error {
+        try_files /$1/404.html /404.html =404;
+    }
+}

exampleSite/layouts/shortcodes/code/deployment-docker-remove.html

@@ -0,0 +1 @@
+$ docker rm mysite

exampleSite/layouts/shortcodes/code/deployment-docker-run.html

@@ -0,0 +1,5 @@
+$ docker run \
+  -p 2333:80 \
+  --name mysite \
+  --restart=always \
+  mysite

exampleSite/layouts/shortcodes/code/deployment-docker-start.html

@@ -0,0 +1 @@
+$ docker start mysite

exampleSite/layouts/shortcodes/code/deployment-docker-stop.html

@@ -0,0 +1 @@
+$ docker stop mysite