From 113a1931b7ff96f3ccf7e9144282947378b11eee Mon Sep 17 00:00:00 2001 From: Seven Du Date: Tue, 6 Aug 2024 00:27:04 +0800 Subject: [PATCH] add dev docker and instruction to watch file changes and update on the fly --- .gitignore | 3 ++ Dockerfile-dev | 9 +++++ Makefile | 23 +++++++++++++ docker-compose-dev.yml | 21 ++++++++++++ docs/chapter_appendix/contribution.md | 33 +++++++++++++++++++ zh-hant/docs/chapter_appendix/contribution.md | 33 +++++++++++++++++++ 6 files changed, 122 insertions(+) create mode 100644 Dockerfile-dev create mode 100644 Makefile create mode 100644 docker-compose-dev.yml diff --git a/.gitignore b/.gitignore index 190a18d75..8b4f346b0 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ # test script test.sh + +.env + diff --git a/Dockerfile-dev b/Dockerfile-dev new file mode 100644 index 000000000..2ef7f0413 --- /dev/null +++ b/Dockerfile-dev @@ -0,0 +1,9 @@ +FROM python:3.10.0-alpine + +ENV PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple +RUN pip install --upgrade pip +RUN pip install mkdocs-material==9.5.5 mkdocs-glightbox + +WORKDIR /hello-algo + +EXPOSE 8000 diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..11274093d --- /dev/null +++ b/Makefile @@ -0,0 +1,23 @@ +VERBOSE=--verbose + +all: # do nothing by default + @echo "usage: make [build-docker|run-dev|dev|stop|sh]" + +build-docker: # build dev container + # docker build -t hello-algo-dev -f Dockerfile-dev . + docker compose -f docker-compose-dev.yml build + +buildx-docker: + docker build -t hello-algo-dev -f Dockerfile-dev . --load + +run-dev: # run in background + docker compose -f docker-compose-dev.yml up -d + +dev: # run dev container + docker compose -f docker-compose-dev.yml $(VERBOSE) up + +stop: # stop dev container + docker compose -f docker-compose-dev.yml down + +sh: # go to dev container shell + docker exec -it hello-algo-dev sh diff --git a/docker-compose-dev.yml b/docker-compose-dev.yml new file mode 100644 index 000000000..19ef62f50 --- /dev/null +++ b/docker-compose-dev.yml @@ -0,0 +1,21 @@ +services: + hello-algo-dev: + build: + context: . + dockerfile: Dockerfile-dev + image: hello-algo-dev + container_name: hello-algo-dev + ports: + - "${HTTP_PORT:-8000}:8000" + # tty: true + # stdin_open: true + entrypoint: + # - "/bin/sh" + - mkdocs + - serve + - -a + - 0.0.0.0:8000 + volumes: + - ./:/hello-algo + - ./docs:/hello-algo/build/docs + - ./overrides:/hello-algo/build/overrides diff --git a/docs/chapter_appendix/contribution.md b/docs/chapter_appendix/contribution.md index ad5a56545..dfa8af967 100644 --- a/docs/chapter_appendix/contribution.md +++ b/docs/chapter_appendix/contribution.md @@ -45,3 +45,36 @@ docker-compose up -d ```shell docker-compose down ``` + +### 开发预览 + +上述 Docker 部署生成的是最终版本。在开发环境中，如果要实时预览修改效果，可以使用以下命令： + +```shell +mkdocs serve +``` + +然后在浏览器中打开 `http://localhost:8000` 即可实时预览。 + +如果本地没有安装 mkdocs 环境，也可以使用 Docker 方式预览。 + +```shell +make build # 构建 Docker 开发镜像 +make run-dev # 启动 Docker 开发镜像到后台 +``` + +镜像启动后，会监听 `8000` 端口，与上一节的 Docker 部署中一样，这是特意为之的，目标是为了减少端口占用，同时只启动一个 Docker 容器，对不熟悉 Docker 的同学少造成一些困扰。当然，如果你想启动到另外的端口，只需要在 `hello-algo` 目录下创建一个 `.env` 文件，内容如下。 + +```shell +HTTP_PORT=9000 +``` + +此外，在日常使用中还可以使用如下命令。 + +```shell +make run # 启动 Docker 开发镜像开前台，便于调试 +make stop # 停止 Docker 开发镜像 +make shell # 进入 Docker 开发镜像的 shell +``` + +如果没有 `make` 工具，则可以参照 `Makefile` 文件中对应的命令手动执行。 diff --git a/zh-hant/docs/chapter_appendix/contribution.md b/zh-hant/docs/chapter_appendix/contribution.md index e5e000b6e..c08a6e82a 100644 --- a/zh-hant/docs/chapter_appendix/contribution.md +++ b/zh-hant/docs/chapter_appendix/contribution.md @@ -45,3 +45,36 @@ docker-compose up -d ```shell docker-compose down ``` + +### 開發預覽 + +上述 Docker 部署生成的是最終版本。在開發環境中，如果要實時預覽修改效果，可以使用以下命令： + +```shell +mkdocs serve +``` + +然後在瀏覽器中打開 `http://localhost:8000` 即可實時預覽。 + +如果本地沒有安裝 mkdocs 環境，也可以使用 Docker 方式預覽。 + +```shell +make build # 構建 Docker 開發鏡像 +make run-dev # 啟動 Docker 開發鏡像到後台 +``` + +鏡像啟動後，會監聽 `8000` 端口，與上一節的 Docker 部署中一樣，這是特意為之的，目標是為了減少端口佔用，同時只啟動一個 Docker 容器，對不熟悉 Docker 的同學少造成一些困擾。當然，如果你想啟動到另外的端口，只需要在 `hello-algo` 目錄下創建一個 `.env` 文件，內容如下。 + +```shell +HTTP_PORT=9000 +``` + +此外，在日常使用中還可以使用如下命令。 + +```shell +make run # 啟動 Docker 開發鏡像開前台，便於調試 +make stop # 停止 Docker 開發鏡像 +make shell # 進入 Docker 開發鏡像的 shell +``` + +如果沒有 `make` 工具，則可以參照 `Makefile` 文件中對應的命令手動執行。