Feature: support dockerized builds of current source-code

[marcellodesales]

🎉 Support containers

• I'm on my first day learning Rust 🦀 and Cargo 🏗️ and I must say it's good...
  • However, there's a lot of overhead for users who just want to use this amazing project.
• This is a very simple example to support a Docker image with just 25MB built from the current code
  • I can push support for CI/CD using Github Actions, publish dev images to Github Docker Registry and push prod docker images to the official Docker Registry.
• This DOES SUPPORT LIVE RELOAD!
  • If a developer changes the local files and refresh the page, the server will automatically render changes!

🏗️ Docker image build

NOTE: The final image is very minimal with Alpine Linux with 25MB

The build below is performed from the source-code, and not from an external installation. It is building a single platform version for simplicity.

$ docker buildx build --platform linux/amd64 -t rust-lang/mdbook -o type=docker  .
[+] Building 2.8s (23/23) FINISHED
 => [internal] load build definition from Dockerfile                                                                                                                     0.0s
 => => transferring dockerfile: 2.17kB                                                                                                                                   0.0s
 => [internal] load .dockerignore                                                                                                                                        0.0s
 => => transferring context: 2B                                                                                                                                          0.0s
 => [internal] load metadata for docker.io/library/alpine:3.16.0                                                                                                         2.0s
 => [internal] load metadata for docker.io/rustlang/rust:nightly-buster-slim                                                                                             1.4s
 => [auth] library/alpine:pull token for registry-1.docker.io                                                                                                            0.0s
 => [auth] rustlang/rust:pull token for registry-1.docker.io                                                                                                             0.0s
 => [runtime 1/3] FROM docker.io/library/alpine:3.16.0@sha256:686d8c9dfa6f3ccfc8230bc3178d23f84eeaf7e457f36f271ab1acc53015037c                                           0.0s
 => => resolve docker.io/library/alpine:3.16.0@sha256:686d8c9dfa6f3ccfc8230bc3178d23f84eeaf7e457f36f271ab1acc53015037c                                                   0.0s
 => [builder  1/11] FROM docker.io/rustlang/rust:nightly-buster-slim@sha256:609c65daad3c69f9a37717e45d794e2eab99ad488dc5d492b8fc85c97c1df531                             0.0s
 => => resolve docker.io/rustlang/rust:nightly-buster-slim@sha256:609c65daad3c69f9a37717e45d794e2eab99ad488dc5d492b8fc85c97c1df531                                       0.0s
 => [internal] load build context                                                                                                                                        0.0s
 => => transferring context: 4.94kB                                                                                                                                      0.0s
 => CACHED [builder  2/11] RUN apt-get update && apt-get install -y git                                                                                                  0.0s
 => CACHED [builder  3/11] WORKDIR /usr/src/github.com/rust-lang                                                                                                         0.0s
 => CACHED [builder  4/11] RUN USER=root cargo new mdBook                                                                                                                0.0s
 => CACHED [builder  5/11] COPY Cargo.toml Cargo.lock /usr/src/github.com/rust-lang/mdBook                                                                               0.0s
 => CACHED [builder  6/11] COPY examples /usr/src/github.com/rust-lang/mdBook/examples                                                                                   0.0s
 => CACHED [builder  7/11] WORKDIR /usr/src/github.com/rust-lang/mdBook                                                                                                  0.0s
 => CACHED [builder  8/11] RUN rustup target add x86_64-unknown-linux-musl                                                                                               0.0s
 => CACHED [builder  9/11] RUN cargo build -vv --config "net.git-fetch-with-cli=true" --target x86_64-unknown-linux-musl --release                                       0.0s
 => CACHED [builder 10/11] COPY src /usr/src/github.com/rust-lang/mdBook/src                                                                                             0.0s
 => CACHED [builder 11/11] RUN cargo build --locked --bin mdbook --release --target x86_64-unknown-linux-musl                                                            0.0s
 => CACHED [runtime 2/3] COPY --from=builder /usr/src/github.com/rust-lang/mdBook/target/x86_64-unknown-linux-musl/release/mdbook /usr/local/bin/mdbook                  0.0s
 => CACHED [runtime 3/3] RUN echo "I am running on linux/arm64, building for linux/amd64" > /etc/build.log                                                               0.0s
 => exporting to oci image format                                                                                                                                        0.7s
 => => exporting layers                                                                                                                                                  0.0s
 => => exporting manifest sha256:f658cf0db29cb5655960164f745fbd841fb0dbba53f2b387e60c5e23f360459b                                                                        0.0s
 => => exporting config sha256:55c34204ee9e1fea12a11af808615f46f89cb428a3c6ff1e46c1bade9282a26a                                                                          0.0s
 => => sending tarball                                                                                                                                                   0.7s
 => importing to docker                                                                                                                                                  0.0s

• The file size can be inspected as follows:

$ docker images | grep mdbook
rust-lang/mdbook   latest  55c34204ee9e   27 minutes ago  24.8MB

🏃 Running a server

• This is a container running with a volume to the md source-code in the current dir mounted
• It also exposes a port number for the service to be reused

$ ls -la $(pwd)/src
total 24
drwxr-xr-x  13 mdesales  staff   416 Feb 22 14:06 .
drwxr-xr-x  12 mdesales  staff   384 Feb 22 14:06 ..
-rw-r--r--   1 mdesales  staff   980 Feb 22 14:06 README.md
-rw-r--r--   1 mdesales  staff  4764 Feb 22 14:06 SUMMARY.md
drwxr-xr-x  10 mdesales  staff   320 Feb 22 14:06 assets
drwxr-xr-x   7 mdesales  staff   224 Feb 22 14:06 data
drwxr-xr-x  19 mdesales  staff   608 Feb 22 14:06 infra
drwxr-xr-x   7 mdesales  staff   224 Feb 22 14:06 monitoring
drwxr-xr-x   7 mdesales  staff   224 Feb 22 14:06 onboard
drwxr-xr-x  17 mdesales  staff   544 Feb 22 14:06 services
drwxr-xr-x   4 mdesales  staff   128 Feb 22 14:06 structure
drwxr-xr-x  43 mdesales  staff  1376 Feb 22 14:06 support
drwxr-xr-x  17 mdesales  staff   544 Feb 22 14:06 tips

• You can then mount the volume and the desired port for local development server.

$ docker run -ti -v $(pwd)/src:/src -p 3000:3000 rust-lang/mdbook
2023-02-23 03:13:24 [INFO] (mdbook::book): Book building has started
2023-02-23 03:13:24 [INFO] (mdbook::book): Running the html backend
2023-02-23 03:13:29 [INFO] (mdbook::cmd::serve): Serving on: http://0.0.0.0:3000
2023-02-23 03:13:29 [INFO] (warp::server): Server::run; addr=0.0.0.0:3000
2023-02-23 03:13:29 [INFO] (warp::server): listening on http://0.0.0.0:3000
2023-02-23 03:13:29 [INFO] (mdbook::cmd::watch): Listening for changes...

• While the server is running, users can also change the contents of any of the files of the mapped volume and enjoy the live reloads!
  • The server will log the file changed and refresh the UI with the latest version

2023-02-23 03:28:47 [INFO] (mdbook::book): Running the html backend
2023-02-23 03:28:54 [INFO] (mdbook::cmd::serve): Files changed: ["/src/onboard/.requirements.md.swp"]
2023-02-23 03:28:54 [INFO] (mdbook::cmd::serve): Building book...
2023-02-23 03:28:54 [INFO] (mdbook::book): Book building has started
2023-02-23 03:28:54 [INFO] (mdbook::book): Running the html backend
2023-02-23 03:29:05 [INFO] (mdbook::cmd::serve): Files changed: ["/src/onboard/.requirements.md.swp", "/src/onboard/requirements.md"]
2023-02-23 03:29:05 [INFO] (mdbook::cmd::serve): Building book...
2023-02-23 03:29:05 [INFO] (mdbook::book): Book building has started
2023-02-23 03:29:05 [INFO] (mdbook::book): Running the html backend

🐳 Docker compose option

• We can drop the following docker-compose.yaml for users to run locally
• Pushed to the repo as well
• Starting the server becomes even simpler to test the test-book

NOTE The command below builds the docker image with for the platform linux/amd64 and starts a container loading the sources from the dir test_book on this repo.

$ docker compose up --build
[+] Running 1/1
 ⠿ Container handbook-mdbook-1  Recreated                                                                                                                                0.2s
Attaching to rustlang-mdbook
rustlang-mdbook  | 2023-02-24 01:00:05 [INFO] (mdbook::book): Book building has started
rustlang-mdbook  | 2023-02-24 01:00:06 [INFO] (mdbook::book): Running the html backend
rustlang-mdbook  | 2023-02-24 01:00:11 [INFO] (mdbook::cmd::serve): Serving on: http://0.0.0.0:3000
rustlang-mdbook  | 2023-02-24 01:00:11 [INFO] (warp::server): Server::run; addr=0.0.0.0:3000
rustlang-mdbook  | 2023-02-24 01:00:11 [INFO] (warp::server): listening on http://0.0.0.0:3000
rustlang-mdbook  | 2023-02-24 01:00:11 [INFO] (mdbook::cmd::watch): Listening for changes...
[+] Running 1/1

🌐 Testing in container

docker run -ti --network mdbook_default alpine/lynx mdbook:3000

[KFearsoff]

@rustbot label +A-Installation +C-enhancement -S-waiting-on-review +S-waiting-on-author

[marcellodesales]

Thank you @KFearsoff for the awesome review!!! I will resolve the conversations and send additional PR changes!

[marcellodesales]

@KFearsoff Everything is better now... Please review it and let me know!

[KFearsoff]

@rustbot label -S-waiting-on-author

[marcellodesales]

@KFearsoff Just added the "/" to the last conversation needed...! Hope this is it!!! 👍

[marcellodesales]

Happy new year! When will this be merged?

@rustbot ready

[marcellodesales]

Do we have anyone to review this?

[ehuss]

Thanks for the PR! Unfortunately I don't really understand what this PR is for, the description seems to be missing an explanation of why it is being proposed. There are precompiled binaries available for several platforms, which should be rather easy to download and use. If this is for development of mdbook itself, I think installing Rust shouldn't be too much of a hurdle to get started, and there shouldn't be anything else besides that. There are official docker images if that is your preferred method of using it.

I think if you want, you can put a page on the wiki with your example workflow. Otherwise, I probably don't want to maintain a docker image.