Skip to content

Commit b4f2909

Browse files
OVH-Team-GuidesOVH-Team-Guides
authored
Merge pull request #4436 from ovh/BV-AI-deploy-docker-image
AI Deploy : new tutorial
2 parents 36b52bb + 17f63ce commit b4f2909

19 files changed

+4594
-0
lines changed

‎pages/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -791,6 +791,7 @@
791791
+ [AI Deploy - Apps portfolio](platform/ai/deploy_guide_05_app_portfolio)
792792
+ [AI Deploy - Billing and lifecycle](platform/ai/deploy_guide_06_billing_concept)
793793
+ [Tutorials](public-cloud-ai-and-machine-learning-ai-deploy-tutorials)
794+
+ [AI Deploy - Tutorial - Build & use a custom Docker image](platform/ai/deploy_tuto_12_build_custom_image)
794795
+ [AI Deploy - Tutorial - Build & use a Streamlit image](platform/ai/deploy_tuto_01_streamlit)
795796
+ [AI Deploy - Tutorial - Deploy a simple app with Flask](platform/ai/deploy_tuto_02_flask)
796797
+ [AI Deploy - Tutorial - Deploy an app for audio classification task using Streamlit](platform/ai/deploy_tuto_03_streamlit_sounds_classification)

‎pages/platform/ai/deploy_tuto_12_build_custom_image/guide.de-de.md

Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
---
2+
title: AI Deploy - Tutorial - Build & use a custom Docker image
3+
slug: deploy/build-use-custom-image
4+
excerpt: Explanations on how to build and use your own custom image
5+
section: AI Deploy - Tutorials
6+
order: 00
7+
updated: 2023-03-29
8+
routes:
9+
canonical: 'https://docs.ovh.com/gb/en/publiccloud/ai/deploy/build-use-custom-image/'
10+
---
11+
12+
**Last updated 29th March, 2023.**
13+
14+
## Objective
15+
16+
This tutorial covers the process of building your own Docker image for AI Deploy. After detailing major guidelines, we will cover a quick example.
17+
18+
## Requirements
19+
20+
- Access to the [OVHcloud Control Panel](https://www.ovh.com/auth/?action=gotomanager&from=https://www.ovh.de/&ovhSubsidiary=de)
21+
- A **Public Cloud** project
22+
- A [user for AI Deploy](https://docs.ovh.com/de/publiccloud/ai/users)
23+
- [Docker](https://www.docker.com/get-started) installed on a personal computer or a virtual machine
24+
- Knowledge about building a Docker image (see the [official Getting Started guide](https://docs.docker.com/get-started/))
25+
26+
## Quick overview
27+
28+
AI Deploy main goal is to simplify AI models or applications deployment, release them in production, with resiliency and security, in a few seconds.
29+
Each application is linked to compute resources such as CPUs or GPUs, and can be accessed through an HTTP Endpoint provided by AI Deploy for each app.
30+
31+
In order to be deployed, your model or application **has to be containerised**, inside a Docker image. Containers provide isolation but also flexibility for your deployments.
32+
The Docker images that you build can be deployed locally, with OVHcloud AI Deploy but also with cloud competitors such as AWS or GCP.
33+
34+
Inside your Docker image, you are free to install almost anything and everything as long as you follow guidelines below.
35+
36+
AI Deploy accept images from **public** or **private** repositories. In short, we can summarize AI deploy with the following schema:
37+
38+
39+
![image](images/ai_deploy_concept.png){.thumbnail}
40+
41+
42+
## Guidelines to follow
43+
44+
### Start from an existing Docker image
45+
46+
Instead of starting from scratch, feel free to start from an existing Docker image, as long as it is compliant with the following guidelines.
47+
For example, you can start from 'python', from 'alpine' or equivalent.
48+
49+
If you need to work with GPUs, please read the next paragraph.
50+
51+
### Use specific images with CUDA drivers for GPUs
52+
53+
> [!primary]
54+
>
55+
> If you want to communicate with our **GPU** hardware in your **AI Deploy apps**, the base image should have **cuda drivers installed**.
56+
57+
Here is a potential list of official base images (featuring **cuda drivers**) that you can use:
58+
59+
- [pytorch/pytorch:latest](https://hub.docker.com/r/pytorch/pytorch)
60+
- [tensorflow/tensorflow:latest-gpu](https://hub.docker.com/r/tensorflow/tensorflow)
61+
- [huggingface/transformers-pytorch-gpu:latest](https://hub.docker.com/r/huggingface/transformers-pytorch-gpu/) (docker pull huggingface/transformers-pytorch-gpu:latest)
62+
- [mxnet/python](https://hub.docker.com/r/mxnet/python)
63+
- [nvidia/cuda](https://hub.docker.com/r/nvidia/cuda)
64+
65+
For example, if you want to start from the base image `tensorflow/tensorflow:latest-gpu`:
66+
67+
```{.console}
68+
FROM tensorflow/tensorflow:latest-gpu
69+
```
70+
71+
### Use the linux/amd64 architecture
72+
73+
Your Docker image has to support at least the `linux/amd64` platform to be deployed correctly. Otherwise deployment will fail.
74+
75+
When you invoke a build, you can set the `--platform` flag to specify the target platform for the build output, `linux/amd64`.
76+
This is especially relevant if you use newer Apple computers (M1/M2/... chipsets) or ARM-based computers.
77+
78+
```{.console}
79+
docker buildx build --platform linux/amd64,linux/arm64 ...
80+
```
81+
82+
More information can be found in the [official Docker documentation](https://docs.docker.com/build/building/multi-platform/).
83+
84+
### Create an OVHcloud user and a working directory
85+
86+
Deployed containers are not run as root, but by an “OVHcloud” user with **UID 42420**.
87+
It means that if you want to be able to write in a specific directory at runtime, you will have to give it specific rights.
88+
89+
This is the case in the vast majority of use cases.
90+
91+
You can do it with the following instructions:
92+
93+
94+
```{.console}
95+
# Define a working directory called workspace
96+
WORKDIR /workspace
97+
98+
# Copy some files from your computer to the Docker image
99+
COPY my_app.py /workspace/
100+
COPY my_models /workspace/my_models/
101+
102+
# Create a HOME dedicated to the OVHcloud user (42420:42420)
103+
RUN chown -R 42420:42420 /workspace
104+
ENV HOME=/workspace
105+
106+
# Change the ownership of any other useful directory to the OVHcloud user (42420:42420)
107+
RUN chown -R 42420:42420 <another_useful_directory>
108+
109+
# Run your app
110+
CMD [ "python3" , "/workspace/my_app.py" ]
111+
```
112+
113+
### Install dependencies via apt or pip
114+
115+
Usually, Python or Linux packages will be required for your application. You can follow [Docker best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) for that, meaning install dependencies with `apt` or `pip`.
116+
117+
Here is a compliant example:
118+
119+
```{.console}
120+
RUN apt-get update && apt-get install -y \
121+
git \
122+
other_linux_packages \
123+
... \
124+
125+
# Install few Python requirements, such as pandas, scikit-learn, taipy...
126+
COPY requirements.txt /workspace/requirements.txt
127+
RUN pip install -r requirements.txt
128+
```
129+
130+
### Manage output data effectively (S3, ...)
131+
132+
Just like AI Notebooks and AI Training, AI Deploy is easily connected to remote storage such as S3 object storage containers at launch.
133+
However, unlike AI Notebooks and AI Training, AI Deploy **does NOT** synchronise data back to your remote storage.
134+
135+
If you need to write data somewhere, for example output from your AI model (generated images), your code application should include storage connection.
136+
For example, you can use the Python `Boto3` library when using Python and S3.
137+
138+
Be careful, **if you write data directly in your working directory, it will be lost when you stop your application**.
139+
140+
### Use environment variables for dynamic values
141+
142+
> [!primary]
143+
>
144+
> For sensitive data such as passwords or tokens, consider using [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/).
145+
146+
Sometimes, instead of hardcoding a variable inside a Dockerfile, it is much more powerful to pass variables during deployment. Docker provides this option natively through the `--env` argument, and OVHcloud AI tools follow the same logic.
147+
148+
During AI Deploy app creation, you will be able to pass environment variables via CLI, API or UI in the control panel. In your Dockerfile, you can gather theses variables with the `ENV` value.
149+
150+
For example, you can launch a new app with two variables like this:
151+
152+
```
153+
ovhai run app <my_docker_image> -e LANGUAGE=english TOKEN=12345678
154+
```
155+
156+
In your Dockerfile, you can easily reuse the variables:
157+
158+
159+
```{.console}
160+
# no default value
161+
ENV LANGUAGE
162+
ENV TOKEN
163+
164+
# a default value
165+
ENV foo /bar
166+
# or ENV foo=/bar
167+
168+
# ENV values can be used during the build
169+
ADD . $foo
170+
# or ADD . ${foo}
171+
# translates to: ADD . /bar
172+
```
173+
174+
### Exposing your model or application with an API
175+
176+
Inside your Dockerfile, you will need to expose your model or application so anyone can use it. The easiest way is to expose API via REST endpoint.
177+
The most popular open source frameworks for exposing APIs are [Flask]() and [Fast API]().
178+
179+
You can find a basic example in the section below, and more advanced tutorials in our [AI Deploy documentation](https://docs.ovh.com/de/publiccloud/ai/).
180+
181+
### Exposing your application with a web frontend
182+
183+
While an API is useful for automation and code, sometimes you will need to expose your application or model through a web interface.
184+
185+
AI Deploy is fully compliant with multiple frontend frameworks, such as [Streamlit](https://streamlit.io/), [Gradio](https://gradio.app/) or [Taipy](https://www.taipy.io/).
186+
You can of course also build your own frontend with your favourite tools, such as HTML/CSS.
187+
188+
You can find a basic example in the section below, and more advanced tutorials in our [AI Deploy documentation](https://docs.ovh.com/de/publiccloud/ai/).
189+
190+
## Basic example: Write your own Dockerfile and build your image
191+
192+
Here we will build a basic Docker image, following the guidelines.
193+
194+
### Prepare the Dockerfile
195+
196+
Create a new file and name it `Dockerfile`, following the guidelines.
197+
198+
1. First you need to choose a base image to start from.
199+
2. Install what you need as dependencies with `apt` or `pip`. Bash command instructions on your Dockerfile should begin with the `RUN` prefix.
200+
3. Copy files from your local directory inside the Docker image with the `COPY` prefix.
201+
4. Allow user "OVHcloud UID 42420" to get specific rights.
202+
5. Run your script.
203+
204+
A basic example can be summarised like this:
205+
206+
```{.console}
207+
# Start from official Python image since we don't need GPU
208+
FROM python:3.9
209+
210+
# Create a working directory
211+
WORKDIR /workspace
212+
213+
# Install a few requirements, such as vim and git
214+
RUN apt-get update && apt-get install -y vim git
215+
216+
# Add your files to your Docker image. NB: best practice is to put data outside, such as S3 storage
217+
ADD example.py /workspace/
218+
ADD dataset.csv /workspace/
219+
220+
# Create a HOME dedicated to the OVHcloud user (42420:42420). Mandatory step
221+
RUN chown -R 42420:42420 /workspace
222+
ENV HOME=/workspace
223+
224+
# Run your script
225+
CMD [ "python3" , "/workspace/example.py" ]
226+
```
227+
228+
### Build your Docker image
229+
230+
Once your **Dockerfile** is complete and matches your needs, you have to choose a name and build the image using the following command in the same directory:
231+
232+
```{.console}
233+
docker build . -t <image-identifier>
234+
```
235+
236+
> [!primary]
237+
>
238+
> The dot argument `.` indicates that your build context (place of the **Dockerfile** and other needed files) is the current directory.
239+
240+
> [!primary]
241+
>
242+
> The `-t` argument allows you to choose the identifier to give to your image. Usually, image identifiers are composed of a **name** and a **version tag** `<name>:<version>`.
243+
244+
> [!warning]
245+
>
246+
> Please make sure that the Docker image you will push in order to run containers using AI products respects the **linux/amd64** architecture. You could, for instance, build your image using **buildx** as follows:
247+
>
248+
> `docker buildx build --platform linux/amd64 ...`
249+
>
250+
251+
## Test it locally (optional)
252+
253+
If you want to verify that your built image is working properly, run the following command:
254+
255+
```{.console}
256+
docker run --rm -it --user=42420:42420 <image-identifier>
257+
```
258+
259+
> [!warning]
260+
>
261+
> Don't forget the `--user=42420:42420` argument if you want to simulate the exact same behaviour that will occur on **AI Deploy apps**. It executes the Docker container as the specific OVHcloud user (user **42420:42420**).
262+
263+
### Push the image to the registry of your choice
264+
265+
Pushing your image to a registry is needed in order for AI Deploy to pull it.
266+
267+
AI Deploy provides a default registry called **Shared registry** where users are able to push their custom images. It is linked with every project by default.
268+
269+
If you prefer using your own private Docker registry instead of the shared one, feel free to use it. Just don't forget to [add your registry in your AI Tools project](https://docs.ovh.com/de/publiccloud/ai/training/add-private-registry) before using it.
270+
271+
The basic commands to push a Docker image to a registry is:
272+
273+
```{.console}
274+
# Add a new registry into OVHcloud AI Tools
275+
ovhai registry add <url>
276+
277+
# Push your image
278+
docker login -u <registry-user> -p <registry-password> <registry>
279+
docker tag <image-identifier> <registry>/<image-identifier>
280+
docker push <registry>/<image-identifier>
281+
```
282+
283+
Example: If you want to push an image named `custom-image` inside a registry `registry.gra.training.ai.cloud.ovh.net`:
284+
285+
```{.console}
286+
# Add a new registry into OVHcloud AI Tools
287+
ovhai registry add my-registry.ai.cloud.ovh.net
288+
289+
docker login -u <registry-user> -p <registry-password> my-registry.ai.cloud.ovh.net
290+
docker tag custom-image:latest my-registry.ai.cloud.ovh.net/custom-image:latest
291+
docker push my-registry.ai.cloud.ovh.net/custom-image:latest
292+
```
293+
294+
If you want to know the exact commands to push on the shared registry, please consult the `Details`{.action} button of the **Shared Docker Registry** section in the **Home** panel of AI Training.
295+
296+
![image](images/shared_registry_details.png){.thumbnail}
297+
298+
299+
## Go further
300+
301+
- Discover some AI Deploy apps we built with API or Web frontend via our [Apps portfolio](https://docs.ovh.com/de/publiccloud/ai/deploy/apps-portfolio/).
302+
303+
## Feedback
304+
305+
Please send us your questions, feedback and suggestions to improve the service:
306+
307+
- On the OVHcloud [Discord server](https://discord.gg/ovhcloud)

0 commit comments

Comments
 (0)