Despliegue en Streamlit Community Cloud con GitHub y secrets.toml

Opciones de despliegue de una app Streamlit

Antes de elegir destino conviene mapear las cuatro rutas principales de despliegue. Streamlit Community Cloud es la mas rápida para apps públicas, Docker da portabilidad, Kubernetes escala horizontalmente y Snowflake integra el runtime dentro del warehouse corporativo:

flowchart LR
    Code["Repositorio GitHub con app.py + requirements.txt"] --> Opt{Destino de despliegue}
    Opt -->|Gratis, público| Cloud[Streamlit Community Cloud]
    Cloud --> CloudURL["https://usuario-app.streamlit.app"]
    Opt -->|Portable, privado| Docker[Imagen Docker]
    Docker --> DockerRun["docker run -p 8501:8501"]
    Opt -->|Escalado horizontal| K8s[Kubernetes]
    K8s --> K8sSvc["Deployment + Service + Ingress"]
    Opt -->|Enterprise data| Snow[Streamlit in Snowflake]
    Snow --> SnowSIS[Runtime dentro del warehouse]
    Cloud -. secrets panel .- Sec["(secrets.toml)"]
    Docker -. env vars .- Sec
    K8s -. ConfigMap/Secret .- Sec
    Snow -. SECRETS de Snowflake .- Sec

¿Qué es Streamlit Community Cloud?

Streamlit Community Cloud es la plataforma de hosting gratuita oficial de Streamlit para aplicaciones públicas. Permite desplegar una app directamente desde un repositorio de GitHub en minutos, sin necesidad de configurar servidores.

• URL resultante: https://{usuario}.streamlit.app/{nombre-repo}
• Límite gratuito: aplicaciones públicas con hasta 1 GB de RAM
• Actualizaciones automáticas al hacer git push

Estructura del repositorio

Un repositorio listo para desplegar necesita como mínimo:

mi-app-streamlit/
├── app.py               # Archivo principal de la aplicación
├── requirements.txt     # Dependencias Python
└── .streamlit/
    └── config.toml      # (opcional) Configuración del tema y servidor

Si la aplicación tiene múltiples páginas:

mi-app-streamlit/
├── app.py
├── requirements.txt
├── pages/
│   ├── dashboard.py
│   └── analisis.py
├── assets/
│   └── logo.png
└── .streamlit/
    └── config.toml

requirements.txt

Lista todas las dependencias con versiones fijas para garantizar reproducibilidad:

# requirements.txt
streamlit==1.40.0
pandas==2.2.3
numpy==2.2.3
matplotlib==3.10.1
plotly==6.0.1
scikit-learn==1.6.1
pillow==11.1.0

Para generar el archivo automáticamente desde tu entorno activo:

# Con pip
pip freeze > requirements.txt

# Con pip-tools (más limpio, solo dependencias directas)
pip install pip-tools
pip-compile requirements.in > requirements.txt

Buena práctica: incluye solo las dependencias que realmente usa tu aplicación. Una lista larga ralentiza el arranque en Community Cloud.

Paso a paso: primer despliegue

1. Sube tu código a GitHub:

git init
git add .
git commit -m "feat: primera versión de la aplicación Streamlit"
git branch -M main
git remote add origin https://github.com/tuusuario/mi-app-streamlit.git
git push -u origin main

2. Accede a share.streamlit.io con tu cuenta de GitHub.

3. Haz clic en "New app" y completa el formulario:

• Repository: tuusuario/mi-app-streamlit
• Branch: main
• Main file path: app.py
• App URL: mi-app (el subdominio personalizado)

4. Haz clic en "Deploy!" La primera compilación puede tardar 2-5 minutos.

Tu aplicación estará disponible en: https://mi-app.streamlit.app

Gestionar secretos desde el panel de Community Cloud

Nunca subas claves de API, contraseñas ni credenciales al repositorio. Usa el panel de Secrets en Community Cloud:

1. En tu app desplegada, haz clic en "⋮" -> Settings -> Secrets
2. Pega el contenido de tu secrets.toml local en el campo de texto

# Contenido a pegar en el panel Secrets de Community Cloud

[database]
host = "mi-base-de-datos.postgres.com"
port = 5432
name = "produccion_db"
user = "app_user"
password = "contraseña_super_secreta"

[apis]
openai_api_key = "sk-..."
stripe_secret_key = "sk_live_..."

[auth]
redirect_uri = "https://mi-app.streamlit.app/oauth2callback"
cookie_secret = "clave_secreta_larga_para_cookies_seguras"

En tu código, accede a los secretos con st.secrets:

import streamlit as st
import psycopg2

# Acceder a secretos individuales
conn = psycopg2.connect(
    host=st.secrets["database"]["host"],
    port=st.secrets["database"]["port"],
    dbname=st.secrets["database"]["name"],
    user=st.secrets["database"]["user"],
    password=st.secrets["database"]["password"]
)

# Acceder con notación punto
api_key = st.secrets.apis.openai_api_key

Actualizar la aplicación

Cada git push a la rama configurada actualiza automáticamente la aplicación en Community Cloud:

# Hacer cambios en el código
git add app.py
git commit -m "fix: corregir filtro de fechas en el dashboard"
git push origin main
# Community Cloud detecta el push y redespliega en ~1-2 minutos

También puedes forzar el redespliegue desde el panel: "⋮" -> Reboot app.

Gestionar dependencias del sistema con packages.txt

Para librerías del sistema operativo (como libGL para OpenCV o ffmpeg para audio):

# packages.txt (en la raíz del repo)
libgl1-mesa-glx
libglib2.0-0
ffmpeg

Configuración del servidor en config.toml

# .streamlit/config.toml

[server]
headless = true        # Necesario en entornos de servidor/cloud
port = 8501

[browser]
gatherUsageStats = false  # Desactivar telemetría

[theme]
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F0F2F6"
textColor = "#31333F"

Privacidad y acceso a la aplicación

Desde el panel de Community Cloud puedes configurar:

• Pública: cualquiera puede acceder con la URL
• Privada: solo los usuarios con acceso al repositorio de GitHub pueden ver la app
• Lista de correos permitidos: restringir el acceso a direcciones de email específicas

Ejemplo de aplicación lista para despliegue

# app.py - Ejemplo completo listo para desplegar en Community Cloud
import streamlit as st
import pandas as pd
import numpy as np
import plotly.express as px

st.set_page_config(
    page_title="Demo CertiDevs",
    page_icon="🎓",
    layout="wide"
)

st.title("🎓 Demo de CertiDevs en Community Cloud")
st.caption("Desplegado automáticamente desde GitHub")

# Generar datos de demostración
@st.cache_data
def generar_datos():
    np.random.seed(42)
    meses = pd.date_range("2025-01", periods=12, freq="MS")
    return pd.DataFrame({
        "mes": meses,
        "usuarios": np.random.randint(800, 1500, 12),
        "cursos_completados": np.random.randint(200, 600, 12),
    })

df = generar_datos()

col1, col2, col3 = st.columns(3)
col1.metric("Usuarios totales", f"{df['usuarios'].sum():,}")
col2.metric("Cursos completados", f"{df['cursos_completados'].sum():,}")
col3.metric("Satisfacción", "4.8 / 5", "+0.2")

fig = px.line(df, x="mes", y=["usuarios", "cursos_completados"],
              title="Evolución mensual", template="streamlit")
st.plotly_chart(fig, use_container_width=True)

st.caption("Versión 1.0 · Desplegada en Streamlit Community Cloud")

# requirements.txt
streamlit==1.40.0
pandas==2.2.3
numpy==2.2.3
plotly==6.0.1

Troubleshooting habitual

| Problema | Causa probable | Solución | |----------|---------------|----------| | ModuleNotFoundError | Dependencia no en requirements.txt | Añadirla al requirements.txt | | App lenta al arrancar | Demasiadas dependencias pesadas | Usar @st.cache_resource para cargar modelos | | Secretos no encontrados | secrets.toml local no subido (correcto) pero no configurado en el panel | Pegar el contenido en el panel Secrets de Community Cloud | | Error de memoria | App supera 1 GB de RAM | Optimizar el código o usar un plan de pago | | App no se actualiza | Push a una rama diferente a la configurada | Verificar la rama en Settings |