Espaços do Docker

Spaces acomodam contêineres Docker personalizados para aplicativos fora do escopo do Streamlit e do Gradio. Os Spaces Docker permitem que os usuários ultrapassem os limites do que era possível com os SDKs padrão. De endpoints FastAPI e Go a aplicativos Phoenix e ferramentas de ML Ops, os Spaces Docker podem ajudar em muitos cenários diferentes.

Configurando Spaces do Docker

Selecionar Docker como SDK ao criar um novo Space inicializa seu Space definindo a propriedade sdk como docker no bloco YAML do seu arquivo README.md. Alternativamente, dado um repositório de Space existente, defina sdk: docker dentro do bloco YAML no topo do arquivo README.md dos seus Spaces. Você também pode alterar a porta exposta por padrão 7860 definindo app_port: 7860. Em seguida, você pode criar um Dockerfile usual.

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

Internamente, você pode ter quantas portas abertas quiser. Por exemplo, você pode instalar o Elasticsearch dentro do seu Space e chamá-lo internamente na porta padrão 9200.

Se você deseja expor aplicativos servidos em múltiplas portas para o mundo externo, uma solução alternativa é usar um proxy reverso, como o Nginx, para despachar requisições da internet em geral (em uma única porta) para diferentes portas internas.

Gerenciamento de Segredos e Variáveis

Você pode gerenciar as variáveis de ambiente de um Space nas Configurações do Space. Leia mais aqui.

Variáveis

Tempo de compilação

Variáveis são passadas como build-args ao construir seu Docker Space. Leia a documentação dedicada do Docker para um guia completo sobre como usar isso no 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

Tempo de execução

As variáveis são injetadas no ambiente do container em tempo de execução.

Segredos

Tempo de compilação

Nos Docker Spaces, o gerenciamento de segredos é diferente por motivos de segurança. Depois de criar um segredo na aba Settings, você pode expor o segredo adicionando a seguinte linha ao seu Dockerfile:

Por exemplo, se SECRET_EXAMPLE for o nome do segredo que você criou na aba Settings, você pode lê-lo no momento da build montando-o em um arquivo e, em seguida, lendo-o com $(cat /run/secrets/SECRET_EXAMPLE).

Veja um exemplo abaixo:

# 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)'

Tempo de execução

Assim como para Variáveis públicas, em tempo de execução, você pode acessar os segredos como variáveis de ambiente. Por exemplo, em Python, você usaria os.environ.get("SECRET_EXAMPLE"). Confira este exemplo de um Space Docker que usa segredos.

Permissões

O contêiner é executado com ID de usuário 1000. Para evitar problemas de permissão, você deve criar um usuário e definir seu WORKDIR antes de qualquer COPY ou download.

# 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.

Se você ainda enfrentar problemas de permissão, talvez seja necessário usar chmod ou chown no seu Dockerfile para conceder as permissões corretas. Por exemplo, se você quiser usar o diretório /data, pode fazer o seguinte:

RUN mkdir -p /data
RUN chmod 777 /data

Você deve sempre evitar chowns desnecessários.

Atualizar os metadados de um arquivo cria uma nova cópia armazenada na nova camada. Portanto, um chown recursivo pode resultar em uma imagem muito grande devido à duplicação de todos os arquivos afetados.

Em vez de corrigir a permissão executando chown:

COPY checkpoint .
RUN chown -R user checkpoint

você deve sempre fazer o seguinte:

COPY --chown=user checkpoint .

(o mesmo vale para o comando ADD)

Persistência de Dados

Os dados gravados no disco são perdidos sempre que seu Docker Space reinicia. Para persistir os dados entre reinícios, você pode anexar um Storage Bucket ao seu Space.

No momento, o volume /data está disponível apenas em tempo de execução, ou seja, você não pode usar /data durante a etapa de build do seu Dockerfile.

Você também pode usar nosso Datasets Hub para casos específicos, onde é possível armazenar estado e dados em um repositório git LFS. Você pode encontrar um exemplo de persistência aqui, que usa a library huggingface_hub para fazer o upload de arquivos para um repositório de dataset de forma programática. Este exemplo de Space, junto com este guia, ajudará você a definir qual solução se encaixa melhor no seu tipo de dados.

Por fim, em alguns casos, você pode querer usar uma solução de armazenamento externo a partir do código do seu Space, como um DB hospedado externamente, S3, etc.

Container Docker com GPU

Você pode executar contêineres Docker com suporte a GPU usando um dos nossos Spaces Hardware com GPU.

Recomendamos usar o nvidia/cuda do Docker Hub como imagem base, que já vem com CUDA e cuDNN pré-instalados.

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).

Saiba Mais

• Exemplo completo de demonstração com Docker
• Lista de exemplos de Spaces do Docker
• Exemplos de Spaces