Skip to content

Commit fdb0b70

Browse files
SamyOubouazizSamyOubouaziz
committed
docs(srv): documentation review
1 parent c167ce6 commit fdb0b70

File tree

1 file changed

+92
-61
lines changed
  • tutorials/deploy-mdbooks-serverless-containers

1 file changed

+92
-61
lines changed

‎tutorials/deploy-mdbooks-serverless-containers/index.mdx‎

Lines changed: 92 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
---
22
meta:
3-
title: Fast deployment of documentation on Serverless Containers with mdbooks
4-
description: Step-by-step guide to deploy mdbooks on Scaleway Serverless Containers.
3+
title: Fast deployment of documentation on Serverless Containers with mdBook
4+
description: Step-by-step guide to deploy mdBooks on Scaleway Serverless Containers.
55
content:
6-
h1: Fast deployment of documentation on Serverless Containers with mdbooks
7-
paragraph: Step-by-step guide to deploy mdbooks on Scaleway Serverless Containers.
8-
tags: docker container deploy serverless
9-
hero: assets/scaleway-umami.webp
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
109
categories:
1110
- containers
1211
- container-registry
@@ -15,100 +14,132 @@ dates:
1514
posted: 2024-10-30
1615
---
1716

18-
`mdBooks` lets you publish modern online books, for product, API documentation, tutorials, course material or anything that requires a clean, easily navigable and customizable presentation.
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.
1918

20-
This tutorial uses `mdbooks` to publish simple documentation but the main goal of this tutorial is to show how simple it is to
21-
pick a project, package it inside an image and deploy it on Serverless Containers.
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.
2220

2321
<Macro id="requirements" />
2422

2523
- A Scaleway account logged into the [console](https://console.scaleway.com)
2624
- [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
27-
- Docker installed on your local machine
25+
- [Docker](https://docs.docker.com/engine/install/) installed on your local machine
2826

29-
## Why deploy on Serverless?
27+
## Why deploy on a Serverless infrastructure?
3028

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

33-
With zero infrastructure management and many tools to integrate in CI/CD environments, an `mdbooks` deployment is well suited to Serverless Containers.
31+
With zero infrastructure management and many tools to integrate in CI/CD environments, an `mdBook` deployment is well suited to Serverless Containers.
3432

35-
## Local setup
33+
## Setting up mdBook locally
3634

37-
1. Follow the [installation instructions](https://rust-lang.github.io/mdBook/guide/installation.html) of mdbooks.
35+
1. Follow the [installation instructions](https://rust-lang.github.io/mdBook/guide/installation.html) of mdBook.
3836

39-
2. Run commands:
40-
- `mdbook init my-first-book` in order to create a sample book.
41-
- `cd my-first-book` to open the directory created by init command.
37+
2. Run the following command to create a sample book:
38+
```
39+
mdbook init my-first-books
40+
```
4241

43-
3. *(Optional)* Edit the content of the book to publish.
42+
3. Run the following command to access the folder created by the previous `init` command:
43+
```
44+
cd my-first-book
45+
```
4446

45-
4. Test the book using the command: `mdbook test`.
47+
4. Optionally, you can edit the content of the book to publish.
4648

47-
## Prepare Container Registry
49+
5. Test the book using the command below:
50+
```
51+
mdbook test
52+
```
53+
54+
## Preparing the Container Registry
4855

4956
<Message type="note">
50-
We recommend using Scaleway Container Registry instead of external registries to avoid errors of rate limiting and risks regarding evolutions of CGU and pricing.
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.
5158
</Message>
5259

53-
1. Create a file named `Dockerfile` in this folder containing the following code:
60+
1. Create a file named `Dockerfile` in the previously created folder, and add the following code to it:
61+
62+
```dockerfile
63+
FROM debian:bookworm-slim
64+
65+
WORKDIR /app
5466

55-
```dockerfile
56-
FROM debian:bookworm-slim
67+
# Copy the necessary files (add your custom files here)
68+
COPY book.toml /app/
69+
COPY src/* /app/src/
5770

58-
WORKDIR /app
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"
5976

60-
# Copy necessary files (add if you have custom files)
61-
COPY book.toml /app/
62-
COPY src/* /app/src/
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+
```
6382

64-
# Install mdbooks binary
65-
RUN apt-get -y update; apt-get -y install curl;
66-
RUN mkdir /home/mdbooks
67-
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
68-
ENV PATH="$PATH:/home/mdbooks"
83+
2. Open the Scaleway console in a web browser, and navigate to the [Container Registry](https://console.scaleway.com/containers/).
6984

70-
# Serve the book:
71-
# 0.0.0.0 is required to listen on public interface, otherwise mdbook will only listen for localhost
72-
# 8080 port is used to match the Serverless Container settings.
73-
ENTRYPOINT ["mdbook", "serve", "-n", "0.0.0.0", "-p", "8080" ]
74-
```
85+
3. Click **+ Create namespace**. [Namespaces](/containers/container-registry/concepts/#namespace) allow you to easily manage the images stored in your Container Registry.
7586

76-
2. Open a web browser on your computer and navigate to the [Container Registry](https://console.scaleway.com/containers/) product in the Scaleway console.
77-
3. Click **Create namespace**. A namespace is used to hold the image.
87+
4. Enter a name for your namespace, or keep the automatically generated one, then click **Create namespace**.
7888

7989
<Message type="note">
80-
A pop-up will appear with information to log into your Container Registry Namespace with `docker login`. This will allow us to push the image later.
90+
For more information on creating a Container Registry namespace, refer to [the dedicated documentation](/containers/container-registry/how-to/create-namespace/).
8191
</Message>
8292

83-
4. Create the namespace and save the registry endpoint. The registry endpoint looks like `rg.<region>.scw.cloud/<namespace>`
93+
## Building and pushing the image
8494

8595
<Message type="note">
86-
Refer to [How to create a namespace](/docs/containers/container-registry/how-to/create-namespace/) for detailed information about Container Registry namespace creation.
96+
Remember to replace the placeholders with the corresponding values in the steps below.
8797
</Message>
88-
## Build and push
8998

90-
1. Run the command `docker build -t rg.<region>.scw.cloud/<namespace>/<image_name>:<tag_name> .`
91-
* **region**: to get this information, check the namespace settings of the namespace you created.
92-
* **image_name**: use the name you want to identify your image, for example `mdbook`.
93-
* **tag_name**: use tags to identify the version of your image, for example `v1`.
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**.
94125

95-
2. Push the image:
96-
`docker push rg.<region>.scw.cloud/<namespace>/<image_name>:<tag>`
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.
97132

98-
## Deploy the Serverless Container
133+
4. Enter a name for your Serverless Container, or keep the automatically generated one.
99134

100-
1. Create a [Serverless Container Namespace](https://console.scaleway.com/containers/namespaces/create) in the Scaleway console.
101-
2. Configure the Serverless Containers. **Important points are:**
102-
* **Image**: Select the Registry namespace, Container and Tag you created before using the dropdown lists.
103-
* **Name**: You can change the default name to use a more meaningful one.
135+
5. Keep the default **resources** and **scaling** values. You can fine-tune them later without any downtime.
104136

105-
You can keep default values of other parameters and fine-tune them later at anytime without downtime.
137+
3. Click **Deploy container** to proceed. The initial deployment of your container can take up to a few minutes.
106138

107-
3. Click **Deploy container** button and wait few seconds for the deployment.
108-
Your Serverless Container is deployed and ready. You can access it via its **endpoint**.
139+
Your Serverless Container is deployed and ready. You can access it via its **endpoint**.
109140

110141
## Going further
111142

112-
* [Monitor logs and metrics](/serverless/containers/how-to/monitor-container/) of your Container.
113-
* [Add a custom domain](/serverless/containers/how-to/add-a-custom-domain-to-a-container/) to your Container.
114-
* Explore [other methods](/serverless/containers/reference-content/deploy-container/) to deploy your Container.
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

Comments
 (0)