Dockerizar una aplicación FastAPI que utiliza SQLAlchemy y Alembic es una excelente forma de garantizar despliegues reproducibles, pero a veces surgen problemas de permisos entre el contenedor y el host al generar o aplicar migraciones. Este artículo explica las causas más comunes del problema y ofrece soluciones prácticas para que tus migraciones funcionen sin fricciones en entornos Docker.
¿Por qué ocurre el problema de permisos: cuando montas el directorio del proyecto del host dentro del contenedor usando bind mount, los archivos creados por procesos dentro del contenedor quedan con el UID y GID del usuario que ejecutó el proceso en el contenedor. Si ese UID no coincide con el UID del usuario en el host, al interactuar desde el host se pueden producir errores de lectura o escritura sobre los archivos de migración generados por Alembic.
Buenas prácticas generales: mantén las carpetas de migraciones versionadas en el repositorio y evita que los contenedores generen nuevas migraciones en producción; genera y revisa migraciones en desarrollo o CI/CD y aplica las migraciones en despliegue. Para aplicar migraciones desde el contenedor usa alembic upgrade head apuntando a la base de datos de destino.
Soluciones concretas:
1) Ejecutar con el mismo UID del host: al lanzar el contenedor usa --user $(id -u):$(id -g) o en docker-compose define user: ${UID}:${GID} y exporta UID y GID en tu entorno o archivo .env. Así los archivos creados por el contenedor tendrán los mismos permisos que el usuario del host y no habrá conflictos al editar o commitear archivos de migración.
2) Crear un usuario en la imagen con UID configurable: en el Dockerfile pasa un ARG USER_ID y crea un usuario con ese UID para que durante el build o el run el proceso use el mismo identificador que el host. Alternativa: en tiempo de build usar ARG y RUN adduser con el UID pasado desde la máquina de build.
3) Cambiar permisos al iniciar el contenedor: añade un entrypoint que haga chown -R appuser:appgroup /app/alembic antes de ejecutar el proceso. Esto garantiza que la carpeta de migraciones tenga la propiedad correcta cada vez que arranque el contenedor. Si usas Alpine considera usar su herramienta de cambio de usuario como su-exec o gosu para bajar privilegios de root de forma segura.
4) Usar volúmenes nombrados o evitar bind mounts para migrations: los volúmenes nombrados de Docker están gestionados por Docker y suelen evitar problemas de permisos entre host y contenedor. Si no necesitas editar migraciones desde el host en tiempo de ejecución, monta las migraciones en un volumen interno.
5) Ejecutar migraciones desde CI/CD o desde el host: otra estrategia es que el pipeline de CI genere y aplique migraciones como paso controlado, o bien aplicar migrations desde la máquina host con alembic apuntando al contenedor de base de datos mediante variables de entorno, evitando así que el contenedor que corre la app escriba archivos en el bind mount.
Ejemplos de comandos útiles: docker-compose run --rm --user $(id -u):$(id -g) web alembic revision --autogenerate -m NuevaMigracion; docker-compose run --rm --user $(id -u):$(id -g) web alembic upgrade head. Configura SQLALCHEMY_DATABASE_URL mediante variables de entorno para que Alembic y la app compartan la misma conexión.
Recomendación práctica: en desarrollo usa el modo que te sea más cómodo para crear migraciones y compromételas al repositorio. En despliegue automatiza alembic upgrade head como parte del arranque controlado por entrypoint o por la orquestación y evita que el contenedor genere migrations en un bind mount sin haber sincronizado UID/GID.
Sobre Q2BSTUDIO: en Q2BSTUDIO somos una empresa de desarrollo de software especializada en aplicaciones a medida y software a medida, con experiencia en integración de bases de datos, despliegue en contenedores y automatización de procesos. Podemos ayudarte a dockerizar tu aplicación FastAPI, resolver conflictos de permisos entre host y contenedor y diseñar pipelines de CI/CD que apliquen migraciones de forma segura. Conocemos los mejores patrones para despliegues en servicios cloud aws y azure y ofrecemos soluciones de inteligencia artificial, ia para empresas, agentes IA y power bi para proyectos de inteligencia de negocio.
Si buscas que te apoyemos en la creación o mejora de aplicaciones, revisa nuestra oferta de desarrollo de aplicaciones a medida o en despliegue y arquitectura revisa nuestros servicios cloud aws y azure. También ofrecemos consultoría en ciberseguridad, pentesting, servicios inteligencia de negocio y soluciones a medida basadas en IA.
Palabras clave: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi.