Espaces Docker

Les Spaces prennent en charge des conteneurs Docker personnalisés pour les applications qui sortent du cadre de Streamlit et Gradio. Les Spaces Docker permettent aux utilisateurs de dépasser les limites de ce qui était auparavant possible avec les SDK standard. Des endpoints FastAPI et Go aux applications Phoenix et aux outils ML Ops, les Spaces Docker peuvent s’avérer utiles dans de nombreuses configurations différentes.

Mise en place des espaces Docker

Sélectionner Docker comme SDK lors de la création d’un nouvel espace initialise votre espace en définissant la propriété sdk sur docker dans le bloc YAML de votre fichier README.md. Sinon, pour un dépôt d’espace existant, définissez sdk: docker dans le bloc YAML en haut du fichier README.md de votre espace. Vous pouvez également modifier le port exposé par défaut 7860 en définissant app_port: 7860. Ensuite, vous pouvez créer un Dockerfile classique.

---
title: Basic Docker SDK Space
emoji: 🐳
colorFrom: purple
colorTo: gray
sdk: docker
app_port: 7860
---

En interne, vous pouvez ouvrir autant de ports que vous le souhaitez. Par exemple, vous pouvez installer Elasticsearch dans votre Space et l’appeler en interne sur son port par défaut 9200.

Si vous souhaitez exposer des applications servies sur plusieurs ports au monde extérieur, un contournement consiste à utiliser un proxy inverse comme Nginx pour acheminer les requêtes provenant d’Internet (sur un port unique) vers différents ports internes.

Gestion des secrets et des variables

Vous pouvez gérer les variables d’environnement d’un Space dans les paramètres du Space. En savoir plus ici.

Variables

Temps de compilation

Les variables sont passées en tant que build-arg lors de la construction de votre Space Docker. Consultez la documentation dédiée de Docker pour un guide complet sur l’utilisation de cette fonctionnalité dans le Dockerfile.

	# Declare your environment variables with the ARG directive
	ARG MODEL_REPO_NAME

	FROM python:latest
	# [...]
	# You can use them like environment variables
	RUN predict.py $MODEL_REPO_NAME

Runtime

Les variables sont injectées dans l’environnement du conteneur à l’exécution.

Secrets

Temps de compilation

Dans Docker Spaces, la gestion des secrets est différente pour des raisons de sécurité. Une fois que vous avez créé un secret dans l'onglet Paramètres, vous pouvez exposer le secret en ajoutant la ligne suivante à votre Dockerfile :

Par exemple, si SECRET_EXAMPLE est le nom du secret que vous avez créé dans l’onglet Settings, vous pouvez le lire au moment de la compilation en le montant dans un fichier, puis en le lisant avec $(cat /run/secrets/SECRET_EXAMPLE).

Voici un exemple ci-dessous :

# Expose the secret SECRET_EXAMPLE at buildtime and use its value as git remote URL
RUN --mount=type=secret,id=SECRET_EXAMPLE,mode=0444,required=true \
 git init && \
 git remote add origin $(cat /run/secrets/SECRET_EXAMPLE)

# Expose the secret SECRET_EXAMPLE at buildtime and use its value as a Bearer token for a curl request
RUN --mount=type=secret,id=SECRET_EXAMPLE,mode=0444,required=true \
	curl test -H 'Authorization: Bearer $(cat /run/secrets/SECRET_EXAMPLE)'

Runtime

Comme pour les Variables publiques, vous pouvez accéder aux secrets sous forme de variables d’environnement à l’exécution. Par exemple, en Python, vous utiliserez os.environ.get("SECRET_EXAMPLE"). Consultez cet exemple de Space Docker qui utilise des secrets.

Autorisations

Le conteneur s'exécute avec l'identifiant utilisateur 1000. Pour éviter les problèmes de permissions, vous devez créer un utilisateur et définir son WORKDIR avant tout COPY ou téléchargement.

# Set up a new user named "user" with user ID 1000
RUN useradd -m -u 1000 user

# Switch to the "user" user
USER user

# Set home to the user's home directory
ENV HOME=/home/user \
	PATH=/home/user/.local/bin:$PATH

# Set the working directory to the user's home directory
WORKDIR $HOME/app

# Try and run pip command after setting the user with `USER user` to avoid permission issues with Python
RUN pip install --no-cache-dir --upgrade pip

# Copy the current directory contents into the container at $HOME/app setting the owner to the user
COPY --chown=user . $HOME/app

# Download a checkpoint
RUN mkdir content
ADD --chown=user https://<SOME_ASSET_URL> content/<SOME_ASSET_NAME>

Always specify the `--chown=user` with `ADD` and `COPY` to ensure the new files are owned by your user.

Si vous rencontrez toujours des problèmes d'autorisation, vous devrez peut-être utiliser chmod ou chown dans votre Dockerfile pour accorder les permissions appropriées. Par exemple, si vous souhaitez utiliser le répertoire /data, vous pouvez faire :

RUN mkdir -p /data
RUN chmod 777 /data

Vous devez toujours éviter les chowns superflus.

La mise à jour des métadonnées d'un fichier crée une nouvelle copie stockée dans la nouvelle couche. Par conséquent, un chown récursif peut entraîner une image très volumineuse en raison de la duplication de tous les fichiers concernés.

Plutôt que de corriger les autorisations en exécutant chown :

COPY checkpoint .
RUN chown -R user checkpoint

vous devriez toujours faire :

COPY --chown=user checkpoint .

(idem pour la commande ADD)

Persistance des données

Les données écrites sur le disque sont perdues à chaque redémarrage de votre Docker Space. Pour conserver les données entre les redémarrages, vous pouvez attacher un Storage Bucket à votre Space.

Pour le moment, le volume /data n'est disponible qu'à l'exécution, c'est-à-dire que vous ne pouvez pas utiliser /data lors de l'étape de construction de votre Dockerfile.

Vous pouvez également utiliser notre Datasets Hub pour des cas spécifiques, où vous pouvez stocker l’état et les données dans un dépôt git LFS. Vous trouverez un exemple de persistance ici, qui utilise la bibliothèque huggingface_hub pour téléverser des fichiers de manière programmatique vers un dépôt de jeu de données. Cet exemple de Space ainsi que ce guide vous aideront à déterminer quelle solution convient le mieux à votre type de données.

Enfin, dans certains cas, vous souhaiterez peut-être utiliser une solution de stockage externe depuis le code de votre Space, comme une base de données hébergée en externe, S3, etc.

Conteneur Docker avec GPU

Vous pouvez exécuter des conteneurs Docker avec prise en charge du GPU en utilisant l'un de nos matériels Spaces adaptés aux GPU.

Nous recommandons d'utiliser nvidia/cuda de Docker Hub comme image de base, qui est livrée avec CUDA et cuDNN préinstallés.

During Docker buildtime, you don't have access to a GPU hardware. Therefore, you should not try to run any GPU-related command during the build step of your Dockerfile. For example, you can't run `nvidia-smi` or `torch.cuda.is_available()` building an image. Read more [here](https://github.com/NVIDIA/nvidia-docker/wiki/nvidia-docker#description).

En savoir plus

• Exemple de démonstration Docker complet
• Liste des exemples de Spaces Docker
• Exemples de Spaces