Fast deployment of documentation on Serverless Containers with mdBook

• docker
• container
• deploy
• serverless
• mdbook
• documentation

mdBook lets you publish modern online books, for product, API documentation, tutorials, course material or anything that requires a clean, easily navigable, and customizable presentation.

This tutorial uses mdbook to publish simple documentation but the main goal of this tutorial is to show how simple it is to pick a project, package it inside an image, and deploy it on Serverless Containers.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• Docker installed on your local machine

Why deploy on a Serverless infrastructure?

Serverless products are perfect for cost efficiency with a pay-as-you-go model, and scale very well.

With zero infrastructure management and many tools to integrate in CI/CD environments, an mdBook deployment is well suited to Serverless Containers.

Setting up mdBook locally

1. Follow the installation instructions of mdBook.

2. Run the following command to create a sample book:

   mdbook init my-first-books
   

3. Run the following command to access the folder created by the previous init command:

   cd my-first-book
   

4. Optionally, you can edit the content of the book to publish.

5. Test the book using the command below:

   mdbook test
   

Preparing the Container Registry

1. Create a file named Dockerfile in the previously created folder, and add the following code to it:

   FROM debian:bookworm-slim
   WORKDIR /app
   # Copy the necessary files (add your custom files here)
   COPY book.toml /app/
   COPY src/* /app/src/
   # Install the mdbooks binary
   RUN apt-get -y update; apt-get -y install curl;
   RUN mkdir /home/mdbooks
   RUN curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=/home/mdbooks
   ENV PATH="$PATH:/home/mdbooks"
   # Serve the book
   # 0.0.0.0 is required to listen on public interface, otherwise mdbook will only listen for localhost
   # 8080 port is used to match the Serverless Container settings.
   ENTRYPOINT ["mdbook", "serve", "-n", "0.0.0.0", "-p", "8080" ]
   

2. Open the Scaleway console in a web browser, and navigate to the Container Registry.

3. Click + Create namespace. Namespaces allow you to easily manage the images stored in your Container Registry.

4. Enter a name for your namespace, or keep the automatically generated one, then click Create namespace.

Building and pushing the image

1. Run the following command in a terminal to sign in to your Container Registry namespace:

   docker login rg.fr-par.scw.cloud/<namespace_name> -u nologin --password-stdin <<< "$SCW_SECRET_KEY"
   

   The message Login Succeeded appears once you are signed in.

2. Run the command below to build and tag your image locally.

   docker build -t rg.<region>.scw.cloud/<namespace_name>/<image_name>:<tag_name> .
   

   • The region and namespace_name can be found in the Namespace settings tab of the namespace you created.
   • image_name: use the name you want to identify your image, such as my-mdbook.
   • tag_name: use tags to identify the version of your image, such as v1.

3. Run the command below to push the image to the Scaleway Container Registry:

   docker push rg.<region>.scw.cloud/<namespace>/<image_name>:<tag>
   

Deploying the Serverless Container

1. In the Serverless Containers section of the Scaleway console, click + Create namespace.

2. Enter a name for your namespace, or keep the automatically generated one, then click Create namespace and add container.

3. Select your image from the registry:

   • Select the Scaleway Container Registry.
   • From the drop-down menu, select the registry namespace previously created.
   • Enter the port previously configured in the Dockerfile (8080 by default)
   • From the drop-down menus, select the container and tag you created before using the dropdown lists.
   • Name: You can change the default name to use a more meaningful one.

4. Enter a name for your Serverless Container, or keep the automatically generated one.

5. Keep the default resources and scaling values. You can fine-tune them later without any downtime.

6. Click Deploy container to proceed. The initial deployment of your container can take up to a few minutes.

Your Serverless Container is deployed and ready. You can access it via its endpoint.

Going further

• Monitor logs and metrics of your container.
• Add a custom domain to your container.
• Explore other methods to deploy your container.