# How to Deploy HowToCook Locally with Docker: A Complete Guide

> Deploy HowToCook locally with Docker using GHCR. Pull the image and run it on port 5000 for instant access to static cooking documentation. Start your local deployment now.

- Repository: [Anduin Xue/HowToCook](https://github.com/Anduin2017/HowToCook)
- Tags: how-to-guide
- Published: 2026-02-27

---

**Pull the pre-built image from GitHub Container Registry with `docker pull ghcr.io/anduin2017/how-to-cook:latest` and run it on port 5000 using `docker run -d -p 5000:80 ghcr.io/anduin2017/how-to-cook:latest` to serve the static cooking documentation locally.**

The HowToCook repository generates a comprehensive cooking guide as a static website using MkDocs and serves it through Nginx. When you deploy locally with Docker, you can run the entire stack without installing Node.js, Python, or MkDocs on your host machine, using either the official pre-built image or building from source.

## Understanding the HowToCook Docker Architecture

The project uses a multi-stage `Dockerfile` located at the repository root to optimize build efficiency and minimize the final image size.

### Stage 1: Lint Environment (Node.js)

The first stage uses a Node-based image to install npm dependencies defined in [`package.json`](https://github.com/Anduin2017/HowToCook/blob/main/package.json), execute the build script, and run the linter. This ensures all Markdown sources are valid before packaging. This stage corresponds to lines 3-9 in the `Dockerfile`.

### Stage 2: Build Environment (Python 3.11)

The second stage starts from `python:3.11`, copies the built site from the lint stage, installs Python dependencies from [`requirements.txt`](https://github.com/Anduin2017/HowToCook/blob/main/requirements.txt), adds system fonts required by WeasyPrint for PDF generation, and runs `mkdocs build` to generate the static site under `/app/site`. This corresponds to lines 12-18 in the `Dockerfile`.

### Stage 3: Runtime Environment (Nginx Alpine)

The final stage uses `nginx:1-alpine` as a lightweight runtime, copying only the generated static files from the Python stage into Nginx's default document root at `/usr/share/nginx/html`. The final image contains no build tools, reducing attack surface and download size. This is implemented in lines 20-23 of the `Dockerfile`.

## Deploy Locally with Docker Using the Pre-Built Image

The fastest way to deploy locally with Docker is to use the GitHub Container Registry image. According to the [`README.md`](https://github.com/Anduin2017/HowToCook/blob/main/README.md) documentation, you can pull and run the container with two commands.

First, pull the latest image:

```bash
docker pull ghcr.io/anduin2017/how-to-cook:latest

```

Then run the container, mapping host port 5000 to the container's port 80:

```bash
docker run -d -p 5000:80 ghcr.io/anduin2017/how-to-cook:latest

```

After the container starts, open your browser to **http://localhost:5000** to view the full HowToCook website.

## Building the Docker Image Locally from Source

If you need to customize the content or modify the build process, you can build the Docker image locally instead of using the pre-built registry image.

First, clone the repository:

```bash
git clone https://github.com/Anduin2017/HowToCook.git
cd HowToCook

```

Build the image with a custom tag:

```bash
docker build -t how-to-cook:dev .

```

Run your locally built image:

```bash
docker run -d -p 5000:80 how-to-cook:dev

```

This approach executes all three stages of the multi-stage `Dockerfile`, including the Node.js linting and Python MkDocs build steps, before serving the site through Nginx.

## Key Files in the Docker Build Process

Several files in the repository root control how you deploy locally with Docker:

- **`Dockerfile`** – The multi-stage build definition that orchestrates the lint, build, and runtime stages using Node, Python 3.11, and Nginx Alpine images.

- **[`requirements.txt`](https://github.com/Anduin2017/HowToCook/blob/main/requirements.txt)** – Python dependencies including MkDocs and WeasyPrint, installed during the Python build stage to generate the static site.

- **[`package.json`](https://github.com/Anduin2017/HowToCook/blob/main/package.json)** – Node.js dependencies for linting and build scripts, used in the first stage to validate Markdown sources.

- **[`README.md`](https://github.com/Anduin2017/HowToCook/blob/main/README.md)** – User-facing documentation that includes the quick-start command for pulling the pre-built image from GitHub Container Registry.

## Summary

- The HowToCook project uses a **three-stage Dockerfile** to build a static MkDocs site and serve it via Nginx.
- To **deploy locally with Docker** quickly, pull `ghcr.io/anduin2017/how-to-cook:latest` and map port 5000 to the container's port 80.
- For **custom builds**, clone the repository and run `docker build -t how-to-cook:dev .` to execute the full lint and build pipeline.
- The final runtime image contains **only static files** and Nginx, with no Node.js or Python tooling, minimizing the attack surface.

## Frequently Asked Questions

### What ports does HowToCook use when I deploy locally with Docker?

The container exposes port 80 internally for Nginx. When you run the container, map a host port (commonly 5000) to port 80 using the `-p` flag, such as `-p 5000:80`, then access the site at `http://localhost:5000`.

### Can I modify the content before building the Docker image?

Yes. Clone the repository with `git clone https://github.com/Anduin2017/HowToCook.git`, edit the Markdown files in the repository, then build the image locally with `docker build -t how-to-cook:dev .`. The Dockerfile will process your modified content through the lint and build stages.

### Why does the Dockerfile use a multi-stage build?

The multi-stage build separates the linting (Node.js), building (Python 3.11 with MkDocs), and runtime (Nginx Alpine) environments. This ensures the final image contains only the compiled static files and Nginx, excluding all build tools and dependencies, which reduces image size and security vulnerabilities.

### Do I need Node.js and Python installed locally to run the container?

No. When you deploy locally with Docker using the pre-built image from GitHub Container Registry, you only need Docker installed. The container includes all necessary runtime components. You only need Node.js and Python if you choose to build the image from source and want to run linting or build steps outside of Docker.