|
| 1 | +--- |
| 2 | +meta: |
| 3 | + title: Fast deployment of documentation on Serverless Containers with mdBook |
| 4 | + description: Step-by-step guide to deploy mdBooks on Scaleway Serverless Containers. |
| 5 | +content: |
| 6 | + h1: Fast deployment of documentation on Serverless Containers with mdBook |
| 7 | + paragraph: Step-by-step guide to deploy mdBooks on Scaleway Serverless Containers. |
| 8 | +tags: docker container deploy serverless mdbook documentation |
| 9 | +categories: |
| 10 | + - containers |
| 11 | + - container-registry |
| 12 | +dates: |
| 13 | + validation: 2024-10-30 |
| 14 | + posted: 2024-10-30 |
| 15 | +--- |
| 16 | + |
| 17 | +[mdBook](https://rust-lang.github.io/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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +<Macro id="requirements" /> |
| 22 | + |
| 23 | +- A Scaleway account logged into the [console](https://console.scaleway.com) |
| 24 | +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization |
| 25 | +- [Docker](https://docs.docker.com/engine/install/) installed on your local machine |
| 26 | + |
| 27 | +## Why deploy on a Serverless infrastructure? |
| 28 | + |
| 29 | +Serverless products are perfect for cost efficiency with a pay-as-you-go model, and scale very well. |
| 30 | + |
| 31 | +With zero infrastructure management and many tools to integrate in CI/CD environments, an `mdBook` deployment is well suited to Serverless Containers. |
| 32 | + |
| 33 | +## Setting up mdBook locally |
| 34 | + |
| 35 | +1. Follow the [installation instructions](https://rust-lang.github.io/mdBook/guide/installation.html) of mdBook. |
| 36 | + |
| 37 | +2. Run the following command to create a sample book: |
| 38 | + ``` |
| 39 | + mdbook init my-first-books |
| 40 | + ``` |
| 41 | + |
| 42 | +3. Run the following command to access the folder created by the previous `init` command: |
| 43 | + ``` |
| 44 | + cd my-first-book |
| 45 | + ``` |
| 46 | + |
| 47 | +4. Optionally, you can edit the content of the book to publish. |
| 48 | + |
| 49 | +5. Test the book using the command below: |
| 50 | + ``` |
| 51 | + mdbook test |
| 52 | + ``` |
| 53 | + |
| 54 | +## Preparing the Container Registry |
| 55 | + |
| 56 | +<Message type="note"> |
| 57 | + We recommend using [Scaleway Container Registry](/containers/container-registry/) instead of external registries to avoid rate limiting errors, and risks linked to CGU and pricing changes. |
| 58 | +</Message> |
| 59 | + |
| 60 | +1. Create a file named `Dockerfile` in the previously created folder, and add the following code to it: |
| 61 | + |
| 62 | + ```docker |
| 63 | + FROM debian:bookworm-slim |
| 64 | +
|
| 65 | + WORKDIR /app |
| 66 | +
|
| 67 | + # Copy the necessary files (add your custom files here) |
| 68 | + COPY book.toml /app/ |
| 69 | + COPY src/* /app/src/ |
| 70 | +
|
| 71 | + # Install the mdbooks binary |
| 72 | + RUN apt-get -y update; apt-get -y install curl; |
| 73 | + RUN mkdir /home/mdbooks |
| 74 | + 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 |
| 75 | + ENV PATH="$PATH:/home/mdbooks" |
| 76 | +
|
| 77 | + # Serve the book |
| 78 | + # 0.0.0.0 is required to listen on public interface, otherwise mdbook will only listen for localhost |
| 79 | + # 8080 port is used to match the Serverless Container settings. |
| 80 | + ENTRYPOINT ["mdbook", "serve", "-n", "0.0.0.0", "-p", "8080" ] |
| 81 | + ``` |
| 82 | + |
| 83 | +2. Open the Scaleway console in a web browser, and navigate to the [Container Registry](https://console.scaleway.com/containers/). |
| 84 | + |
| 85 | +3. Click **+ Create namespace**. [Namespaces](/containers/container-registry/concepts/#namespace) allow you to easily manage the images stored in your Container Registry. |
| 86 | + |
| 87 | +4. Enter a name for your namespace, or keep the automatically generated one, then click **Create namespace**. |
| 88 | + |
| 89 | +<Message type="note"> |
| 90 | + For more information on creating a Container Registry namespace, refer to [the dedicated documentation](/containers/container-registry/how-to/create-namespace/). |
| 91 | +</Message> |
| 92 | + |
| 93 | +## Building and pushing the image |
| 94 | + |
| 95 | +<Message type="note"> |
| 96 | +Remember to replace the placeholders with the corresponding values in the steps below. |
| 97 | +</Message> |
| 98 | + |
| 99 | +1. Run the following command in a terminal to sign in to your Container Registry namespace: |
| 100 | + ``` |
| 101 | + docker login rg.fr-par.scw.cloud/<namespace_name> -u nologin --password-stdin <<< "$SCW_SECRET_KEY" |
| 102 | + ``` |
| 103 | + The message `Login Succeeded` appears once you are signed in. |
| 104 | + |
| 105 | +2. Run the command below to build and tag your image locally. |
| 106 | + |
| 107 | + ``` |
| 108 | + docker build -t rg.<region>.scw.cloud/<namespace_name>/<image_name>:<tag_name> . |
| 109 | + ``` |
| 110 | + |
| 111 | + * The **region** and **namespace_name** can be found in the **Namespace settings** tab of the namespace you created. |
| 112 | + * **image_name**: use the name you want to identify your image, such as `my-mdbook`. |
| 113 | + * **tag_name**: use tags to identify the version of your image, such as `v1`. |
| 114 | + |
| 115 | +3. Run the command below to push the image to the Scaleway Container Registry: |
| 116 | + ``` |
| 117 | + docker push rg.<region>.scw.cloud/<namespace>/<image_name>:<tag> |
| 118 | + ``` |
| 119 | + |
| 120 | +## Deploying the Serverless Container |
| 121 | + |
| 122 | +1. In the [Serverless Containers](https://console.scaleway.com/containers/namespaces/) section of the Scaleway console, click **+ Create namespace**. |
| 123 | + |
| 124 | +2. Enter a name for your namespace, or keep the automatically generated one, then click **Create namespace and add container**. |
| 125 | + |
| 126 | +3. Select your image from the registry: |
| 127 | + * Select the **Scaleway Container Registry**. |
| 128 | + * From the drop-down menu, select the **registry namespace** previously created. |
| 129 | + * Enter the **port** previously configured in the Dockerfile (`8080` by default) |
| 130 | + * From the drop-down menus, select the **container** and **tag** you created before using the dropdown lists. |
| 131 | + * **Name**: You can change the default name to use a more meaningful one. |
| 132 | + |
| 133 | +4. Enter a name for your Serverless Container, or keep the automatically generated one. |
| 134 | + |
| 135 | +5. Keep the default **resources** and **scaling** values. You can fine-tune them later without any downtime. |
| 136 | + |
| 137 | +3. Click **Deploy container** to proceed. The initial deployment of your container can take up to a few minutes. |
| 138 | + |
| 139 | +Your Serverless Container is deployed and ready. You can access it via its **endpoint**. |
| 140 | + |
| 141 | +## Going further |
| 142 | + |
| 143 | +* [Monitor logs and metrics](/serverless/containers/how-to/monitor-container/) of your container. |
| 144 | +* [Add a custom domain](/serverless/containers/how-to/add-a-custom-domain-to-a-container/) to your container. |
| 145 | +* Explore [other methods](/serverless/containers/reference-content/deploy-container/) to deploy your container. |
0 commit comments