Entorno Docker para compilar APKs con Buildozer y Kivy

Compilar aplicaciones Android con Buildozer puede ser un dolor de cabeza por las dependencias del sistema y las versiones de Java o Cython. Para solucionar esto, hemos creado un contenedor Docker basado en Ubuntu que preconfigura todo el entorno (Android SDK, NDK y API 31) de forma automática.

Este Dockerfile automatiza la creación de un sistema limpio y seguro para compilar tu código.

# Usamos una imagen base de Ubuntu estable
FROM ubuntu:22.04
 
# Evitamos prompts interactivos durante la instalación
ENV DEBIAN_FRONTEND=noninteractive
 
# Actualizamos e instalamos dependencias del sistema requeridas por Buildozer y Android SDK/NDK.
# Añadimos 'nano' y herramientas de compilación extra (autoconf, automake, libtool, pkg-config).
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    git \
    zip \
    unzip \
    openjdk-17-jdk \
    build-essential \
    libffi-dev \
    libssl-dev \
    libltdl-dev \
    libsqlite3-dev \
    cmake \
    sudo \
    curl \
    nano \
    autoconf \
    automake \
    libtool \
    pkg-config \
    zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*
 
# Buildozer da errores si se ejecuta como root, así que creamos un usuario
RUN useradd -m -s /bin/bash kivyuser \
    && echo "kivyuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
# A partir de aquí ejecutamos todo como el nuevo usuario
USER kivyuser
 
# Añadimos la ruta de los paquetes pip de usuario al PATH
ENV PATH="/home/kivyuser/.local/bin:${PATH}"
 
# Instalamos Buildozer, wheel y la versión de Cython exacta
RUN pip3 install --user --upgrade pip virtualenv setuptools wheel
RUN pip3 install --user buildozer "Cython==0.29.36"
 
# --- CORRECCIÓN CLAVE ---
# Creamos las carpetas con nuestro usuario ANTES del WORKDIR para evitar que Docker las cree como root.
RUN mkdir -p /home/kivyuser/dummy_app /home/kivyuser/app
 
# --- PRE-INSTALACIÓN DEL SDK/NDK Y API 31 ---
# Entramos al directorio temporal
WORKDIR /home/kivyuser/dummy_app
 
# 1. Inicializamos Buildozer.
# 2. Modificamos el buildozer.spec para usar la API 31.
# 3. Aceptamos las licencias automáticamente.
# 4. Creamos un main.py básico.
# 5. Ejecutamos buildozer. El "|| true" asegura que no aborte la imagen por fallos menores.
# 6. Borramos el proyecto dummy.
RUN buildozer init \
    && sed -i 's/.*android.api =.*/android.api = 31/' buildozer.spec \
    && sed -i 's/.*android.accept_sdk_license =.*/android.accept_sdk_license = True/' buildozer.spec \
    && echo "print('Preparando entorno Android')" > main.py \
    && buildozer android debug || true \
    && rm -rf /home/kivyuser/dummy_app
 
# Establecemos el directorio de trabajo final para montar el volumen de tu código real
WORKDIR /home/kivyuser/app
 
# Comando por defecto (mantiene el contenedor vivo si se ejecuta interactivo)
CMD ["/bin/bash"]

Puntos clave de esta imagen:

• Base robusta: Utiliza Ubuntu 22.04 y desactiva las interacciones manuales durante la instalación de paquetes[cite: 1].
• Dependencias esenciales: Incluye Python 3, Java 17 (openjdk-17-jdk), herramientas de compilación como cmake, autoconf y build-essential[cite: 1].
• Usuario sin privilegios root: Buildozer falla si se ejecuta como root[cite: 1]. El script crea el usuario kivyuser y le otorga permisos de sudo sin contraseña[cite: 1].
• Versiones fijadas: Instala la versión específica Cython==0.29.36 para asegurar la compatibilidad[cite: 1].
• El “Dummy App Trick”: Antes de montar tu código, el Dockerfile crea una aplicación de prueba para forzar la descarga del Android SDK/NDK, apuntando a la API 31 y aceptando las licencias automáticamente[cite: 1]. Esto ahorra horas de descarga cada vez que levantas el contenedor.
• Directorio final: Todo queda preparado en /home/kivyuser/app, que es donde deberás montar el volumen con tu proyecto real[cite: 1].

Para que este contenedor funcione correctamente con tu aplicación, tu archivo buildozer.spec debe estar bien configurado. Aquí tienes un ejemplo optimizado para una app con requerimientos de red y almacenamiento:

[app]
title = ia
package.name = ia
package.domain = org.test
source.dir = .
version = 0.1
requirements = python3, kivy==2.3.0, android, pyjnius, openssl, certifi, plyer
orientation = portrait
android.permissions = INTERNET, READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE, MANAGE_EXTERNAL_STORAGE
android.allow_cleartext = True

Explicación de los parámetros:

• Identificación: La aplicación se llama “ia”, pertenece al dominio org.test y se encuentra en la versión 0.1[cite: 2].
• Dependencias (Requirements): Especifica Kivy en su versión 2.3.0 e incluye librerías críticas como pyjnius (para llamar a la API de Java desde Python), openssl, certifi (para conexiones seguras) y plyer (para acceder al hardware del dispositivo)[cite: 2].
• Permisos de Android: Solicita acceso a Internet (INTERNET) y lectura/escritura profunda del almacenamiento del dispositivo (READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE, MANAGE_EXTERNAL_STORAGE)[cite: 2].
• Redes no seguras: El parámetro android.allow_cleartext = True permite conexiones HTTP que no cuenten con certificado SSL[cite: 2].

Una vez que tienes el Dockerfile y el buildozer.spec junto con tu código fuente (como tu archivo main.py), es el momento de compilar. Abre tu terminal en la carpeta donde tienes estos archivos y sigue estos pasos:

Primero, debes crear la imagen local de Docker. Esto tomará un tiempo la primera vez porque descargará todo el sistema base y el Android SDK.

docker build -t buildozer-env .

Ahora levantaremos el contenedor. El truco aquí es usar -v $(pwd):/home/kivyuser/app. Esto “conecta” tu carpeta actual del ordenador con la carpeta de trabajo dentro de Docker. Así, todo lo que Buildozer genere se guardará directamente en tu disco duro.

docker run -it -v $(pwd):/home/kivyuser/app buildozer-env

Una vez ejecutes el comando anterior, tu terminal cambiará y estarás dentro del contenedor Docker como el usuario kivyuser. Para generar el APK, simplemente ejecuta:

buildozer android debug

El proceso comenzará. Verás cómo descarga dependencias de Python y compila el código. Si todo está correcto, al finalizar verás un mensaje de éxito indicando que el APK se ha generado.

Como montamos el volumen en el paso 2, no necesitas hacer nada especial para sacar el archivo del contenedor. Simplemente escribe exit para salir de Docker.

exit

Si miras en tu carpeta local (la de tu ordenador), verás que ha aparecido una nueva carpeta llamada bin/. ¡Ahí dentro estará tu archivo .apk listo para ser instalado en tu teléfono o subido a tu web!