matbrands/python repository overview

⁠Python 3.12 Alpine Docker Image

Uma imagem Docker leve e otimizada baseada em Python 3.12 com Alpine Linux, pré-configurada com uv como gerenciador de pacotes para instalação rápida de dependências.

⁠Características

• 🐍 Python 3.12 em Alpine Linux (imagem compacta ~180MB)
• ⚡ uv Package Manager - Instalação de pacotes 10-100x mais rápida que pip
• 👤 Usuário não-root - Executa como usuário tux (UID 1000) por segurança
• 🔐 Virtual Environment isolado - Dependências isoladas em /opt/venv
• 🔗 Git clone automático - Suporte nativo para clonar repositórios privados via Git Token
• 📦 Gerenciamento robusto de sinais - Usa dumb-init para propagação correta de sinais
• 🛠️ Entrypoint flexível - Suporta execução customizada de scripts e comandos

⁠Como Usar

⁠1. Execução Básica

docker run -it matbrands/python:3.12

⁠2. Clonar e Executar Repositório

docker run -e GIT_TOKEN=seu_github_token \
           -e GIT_REPO=seu_usuario/seu_repositorio \
           -e BRANCH=main \
           matbrands/python:3.12

Variáveis de Ambiente:

⁠3. Executar Comando Específico

docker run matbrands/python:3.12 python --version

⁠4. Montar Volume Personalizado

docker run -v /seu/local:/opt/python \
           -e CUSTOM_PATH=seu/script \
           matbrands/python:3.12

⁠5. Com Docker Compose

services:
  python:
    image: matbrands/python:3.12
    environment:
      - GIT_TOKEN=${GIT_TOKEN}
      - GIT_REPO=seu_usuario/seu_repositorio
      - BRANCH=main
    volumes:
      - ./seu_codigo:/opt/python
    working_dir: /opt/python

⁠Estrutura da Imagem

/opt/python              # Diretório de trabalho
├── requirements.txt     # Dependências (instaladas automaticamente)
│
/opt/venv               # Python Virtual Environment
├── bin/
│   └── python
├── lib/
│   └── python3.12/
│   
/opt/entrypoint.sh      # Script de inicialização

/home/tux               # Home do usuário não-root

⁠Variáveis de Ambiente Importantes

APP_VERSION=3.12                    # Versão do Python
USER=tux                            # Usuário para execução
USER_ID=1000                        # UID do usuário
HOME=/home/tux                      # Home directory
WORKDIR=/opt/python                 # Diretório de trabalho
VIRTUAL_ENV=/opt/venv               # Caminho do venv
PATH=$PATH:$HOME/.local/bin:$VENV/bin

⁠Comportamentos do Entrypoint

O script entrypoint.sh implementa a seguinte lógica:

1. Se GIT_TOKEN e GIT_REPO estão definidas:

   • Clona o repositório especificado usando token de autenticação
   • Usa branch especificada (padrão: main)
   • Define PYTHONPATH para incluir o repositório

2. Se nenhuma variável Git está definida:

   • Verifica se o repositório já existe localmente
   • Se não existir, falha com erro descritivo

3. Se um comando for passado:

   • Executa o comando ao invés do entrypoint

⁠Exemplos de Uso

⁠Exemplo 1: Script Python Simples

docker run matbrands/python:3.12 python -c "import pydantic; print(pydantic.__version__)"

⁠Exemplo 2: Clonar Repositório Privado e Executar Script

docker run \
  -e GIT_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e GIT_REPO=minhaorg/meu-projeto \
  -e BRANCH=develop \
  -e CUSTOM_PATH=src \
  matbrands/python:3.12

⁠Exemplo 3: Instalar Pacotes Adicionais

FROM matbrands/python:3.12

RUN uv pip install --no-cache-dir \
    pandas \
    numpy \
    scikit-learn

⁠Exemplo 4: Desenvolvimento Local

docker run -it \
  -v $(pwd):/opt/python \
  -w /opt/python \
  matbrands/python:3.12 \
  bash

⁠Segurança

• ✅ Executa como usuário não-root (UID 1000)
• ✅ Alpine Linux reduz superfície de ataque
• ✅ Virtual environment isolado
• ✅ Usa dumb-init para evitar processos zumbis
• ⚠️ IMPORTANTE: Git Token deve ser fornecido apenas em tempo de execução, nunca bake na imagem

⁠Performance

• 📦 Imagem compacta: ~180-200MB
• ⚡ Instalação rápida: uv é ~10-100x mais rápida que pip
• 🚀 Startup rápido: Alpine Linux e camada base otimizada

⁠Troubleshooting

⁠"Error cloning repository with Token"

# Verificar se o GIT_TOKEN está correto
echo "Token: ${GIT_TOKEN}"

# Verificar permissões do token (deve ter acesso repo)
curl -H "Authorization: token ${GIT_TOKEN}" https://api.github.com/user

# Verificar formato correto do repositório
# Deve ser: usuario/repo (sem https:// ou .git)

⁠"CUSTOM_PATH does not exist"

# Verificar estrutura do repositório clonado
docker run -it \
  -e GIT_TOKEN=seu_token \
  -e GIT_REPO=usuario/repo \
  matbrands/python:3.12 \
  find /opt/python -type f -name "*.py" | head -10

⁠Problemas com Virtual Environment

# Ativar venv manualmente
docker run matbrands/python:3.12 \
  bash -c "source /opt/venv/bin/activate && python --version"

⁠Build Local

# Clone ou navegue até a pasta contendo o Dockerfile
cd docker/python

# Build com versão padrão (3.12)
make build

# Build com versão específica
docker build \
  --build-arg APP_VERSION=3.12 \
  -f ./build/Dockerfile ./build/ \
  -t seu-usuario/python:3.12

⁠Versões Suportadas

• 3.12 (atual, recomendado)
• Outras versões podem ser adicionadas ajustando APP_VERSION no build

⁠Dockerfile Base

Esta imagem é construída sobre:

• astral/uv - Gerenciador de pacotes Python ultrarrápido
• Python 3.12 - Runtime Python estável e moderno
• Alpine Linux - Base leve e segura

⁠Contribuições

Para reportar problemas ou sugerir melhorias, entre em contato com o maintainer.

⁠Licença

Proprietary - Desenvolvido por Indicium AI

⁠Maintainer

Matheus M. Brandão
📧 [email protected]⁠

Última atualização: 2026-05-11