Configuración de la ventana acoplable#

Guía completa para configurar Construbot con Docker para el desarrollo local.

Nota

Método recomendado: Docker proporciona el entorno de desarrollo más sencillo y consistente en todas las plataformas.

Descripción general#

El entorno de desarrollo Docker incluye:

  • Django: Aplicación web (puerto 8000)

  • PostgreSQL: Base de datos (puerto 5432)

  • Redis: Agente de caché y apio (puerto 6379)

  • MailHog: Interfaz de prueba de correo electrónico (puerto 8025)

  • Trabajador de apio: Procesamiento de tareas en segundo plano

Todos los servicios se organizan mediante Docker Compose con gestión automática de dependencias.

Instalación#

Paso 1: instale el escritorio Docker#

macOS:

# Using Homebrew
brew install --cask docker

# Or download from: https://www.docker.com/products/docker-desktop

Windows:

Descargue Docker Desktop desde https://www.docker.com/products/docker-desktop

Linux (Ubuntu/Debian):

# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo apt-get install docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

Verificar instalación:

docker --version
# Should show: Docker version 20.10+ or higher

docker-compose --version
# Should show: Docker Compose version 2.0+ or higher

Paso 2: clonar repositorio#

git clone https://github.com/javier-llamas/construbot.git
cd construbot

Paso 3: construir y comenzar#

El proyecto incluye un Makefile con comandos convenientes:

# Build images and start with development settings
make buildev

Este comando:

  1. Modifica .env para establecer DJANGO_SETTINGS_MODULE=construbot.config.settings.local

  2. Establece DJANGO_DEBUG=True

  3. Crea imágenes de Docker

  4. Inicia todos los servicios (postgres, redis, mailhog, django)

  5. Ejecuta migraciones de bases de datos.

  6. Recopila archivos estáticos

Resultado esperado:

Creating network "construbot_default" with the default driver
Creating volume "construbot_postgres_data" with default driver
Creating construbot_postgres_1 ... done
Creating construbot_redis_1    ... done
Creating construbot_mailhog_1  ... done
Creating construbot_django_1   ... done
Running migrations...
Operations to perform:
  Apply all migrations: ...
Applying ...
Collecting static files...

Paso 4: crear superusuario#

make superuser

Se le solicitará:

  • Correo electrónico: Su correo electrónico de administrador (utilizado para iniciar sesión)

  • Contraseña: Contraseña segura

  • Contraseña (nuevamente): Confirmación

Email: admin@example.com
Password:
Password (again):
Superuser created successfully.

Paso 5: Acceder a la Aplicación#

Abra su navegador para:

Inicie sesión con las credenciales de superusuario que acaba de crear.

Configuración de composición de Docker#

El proyecto utiliza docker-compose.yml para la orquestación de servicios.

Descripción general de los servicios#

Django:

django:
  build:
    context: .
    dockerfile: ./compose/local/django/Dockerfile
  image: construbot_local_django
  container_name: construbot_django
  depends_on:
    - postgres
    - redis
    - mailhog
  volumes:
    - .:/app:z
  env_file:
    - ./.env
  ports:
    - "8000:8000"
  command: /start

  • Ejecuta el servidor de desarrollo Django con recarga automática.

  • Monta el directorio actual para cambios de código en vivo

  • Expone el puerto 8000

postgres:

postgres:
  image: postgres:12-alpine
  container_name: construbot_postgres
  volumes:
    - postgres_data:/var/lib/postgresql/data
  environment:
    - POSTGRES_HOST=postgres
    - POSTGRES_PORT=5432
    - POSTGRES_DB=construbot
    - POSTGRES_USER=debug
    - POSTGRES_PASSWORD=debug

  • Utiliza PostgreSQL 12 con Alpine Linux

  • Datos persistentes en volumen con nombre

  • Credenciales de desarrollo predeterminadas

redis:

redis:
  image: redis:6-alpine
  container_name: construbot_redis

  • Redis 6 para almacenamiento en caché y corredor de apio

  • No hay persistencia configurada (solo desarrollo)

correo:

mailhog:
  image: mailhog/mailhog:v1.0.0
  container_name: construbot_mailhog
  ports:
    - "8025:8025"

Configuración del entorno#

El archivo .env controla la configuración específica del entorno.

Variables del entorno de desarrollo#

Cuando ejecuta make buildev, estos se configuran automáticamente:

# Django Settings
DJANGO_SETTINGS_MODULE=construbot.config.settings.local
DJANGO_DEBUG=True
DJANGO_READ_DOT_ENV_FILE=True

# Docker
USE_DOCKER=yes

# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=construbot
POSTGRES_USER=debug
POSTGRES_PASSWORD=debug

# Redis
REDIS_URL=redis://redis:6379/0

# Email (MailHog)
DJANGO_EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=mailhog
EMAIL_PORT=1025

Configuración manual#

Para personalizar la configuración, edite .env:

# Copy example file if needed
cp .env.example .env

# Edit with your preferred editor
nano .env

Consulte Configuración para obtener una referencia completa de las variables.

Flujo de trabajo de desarrollo#

Iniciando el entorno#

# Start all services
make dev

# Or use docker-compose directly
docker-compose up

Esto inicia los servicios sin reconstruir. Úselo cuando:

  • Ya has ejecutado make buildev

  • Ninguna dependencia ha cambiado.

  • Solo quieres iniciar los contenedores.

Detener el medio ambiente#

# Stop all containers
make down

# Or: Ctrl+C in the terminal running docker-compose up

Migraciones de bases de datos#

# Create and apply migrations
make migrations

# Or run manually:
docker-compose run --rm django python manage.py makemigrations
docker-compose run --rm django python manage.py migrate

Accediendo a Django Shell#

# Django shell
make shell

# Or:
docker-compose run --rm django python manage.py shell

>>> from construbot.users.models import User
>>> User.objects.count()
1

Ejecución de comandos de gestión#

# Populate test data
make poblar

# Or run any Django command:
docker-compose run --rm django python manage.py <command>

Ver registros#

# All services
docker-compose logs

# Specific service
docker-compose logs django

# Follow logs (tail -f)
docker-compose logs -f django

Reconstrucción de imágenes#

# Rebuild all images
make buildev

# Force rebuild without cache
docker-compose build --no-cache

Cuándo reconstruir:

  • Después de cambiar requisitos/*.txt

  • Después de modificar Dockerfiles

  • Después de extraer actualizaciones de git con cambios de dependencia

Pruebas en Docker#

Ejecución de pruebas#

# Full test suite with coverage
make test

# Tests with warnings
make warningtest

# Specific test tag
make current  # Runs tests tagged with @tag('current')

Configuración de prueba#

Las pruebas utilizan construbot.config.settings.test que:

  • Utiliza una base de datos SQLite en memoria (más rápida)

  • Desactiva las migraciones para mayor velocidad.

  • Configura ajustes específicos de la prueba

Consulte /contributor/testing/running-tests para obtener más detalles.

Limpieza y reinicio#

Quitar contenedores#

# Stop and remove containers
make clean

# Or:
docker-compose down

Esto preserva:

  • Datos de la base de datos (en volumen)

  • Imágenes construidas

Restablecer base de datos#

# Remove database volume
make cleandb

# Then rebuild:
make buildev
make superuser

Advertencia: ¡Esto elimina todos los datos!

Limpieza completa#

# Remove EVERYTHING (containers, volumes, images)
make cleanhard

Advertencia: Esto elimina:

  • Todos los contenedores

  • Todos los volúmenes (datos de la base de datos)

  • Todas las imágenes construidas

  • Necesitará ejecutar make buildev para comenzar de nuevo

Solución de problemas#

Conflictos portuarios#

Error: «El puerto 8000 ya está asignado»

Solución 1: Detener el servicio conflictivo

# macOS/Linux
lsof -ti:8000 | xargs kill -9

# Or find process ID
lsof -i:8000

Solución 2: Cambiar puerto en docker-compose.yml

django:
  ports:
    - "8001:8000"  # Changed from 8000:8000

Luego acceda a http://localhost:8001

El contenedor no arranca#

Verificar registros:

docker-compose logs django

Problemas comunes:

  1. La base de datos no está lista: Espere unos segundos, Django lo volverá a intentar

  2. Errores de migración: Ejecute realizar migraciones

  3. Dependencias faltantes: Ejecute make buildev para reconstruir

Problemas de permisos de volumen#

Error: «Permiso denegado» al acceder a archivos

Solución (Linux):

# Fix file ownership
sudo chown -R $USER:$USER .

# Or run Docker as root (not recommended)

Errores de conexión a la base de datos#

Error: «no se pudo conectar al servidor»

Compruebe que Postgres se esté ejecutando:

docker-compose ps postgres

Reiniciar postgres:

docker-compose restart postgres

Compruebe DATABASE_URL en .env:

# Should be:
DATABASE_URL=postgresql://debug:debug@postgres:5432/construbot

Sin espacio en disco#

Error: «No queda espacio en el dispositivo»

Limpiar Docker:

# Remove unused images and containers
docker system prune -a

# Check Docker disk usage
docker system df

# If needed, increase Docker Desktop disk allocation
# Docker Desktop → Preferences → Resources → Disk image size

Temas avanzados#

Anulación de redacción de Docker personalizada#

Cree docker-compose.override.yml para personalizaciones locales:

version: '3'

services:
  django:
    ports:
      - "8001:8000"  # Custom port
    environment:
      - CUSTOM_VAR=value

Este archivo se ignora por git y no se confirmará.

Trabajador de apio corriendo#

El proyecto incluye Celery para tareas en segundo plano. Para ejecutar un trabajador:

# In a separate terminal
docker-compose run --rm django celery -A construbot.taskapp worker -l info

O agregue a docker-compose.yml:

celeryworker:
  <<: *django
  container_name: construbot_celeryworker
  depends_on:
    - redis
    - postgres
  ports: []
  command: /start-celeryworker

Depurando con pdb#

Para usar el depurador de Python:

# Start in foreground with stdin attached
docker-compose run --rm --service-ports django

Agregue un punto de interrupción en el código:

import pdb; pdb.set_trace()

Cuando llegue el punto de interrupción, obtendrá un depurador interactivo en su terminal.

Integración IDE#

PyCharm Profesional:

  1. Configurar el intérprete de Python → Docker Compose

  2. Establecer servicio: django

  3. PyCharm utilizará automáticamente el entorno Docker

Código VS:

  1. Instalar la extensión «Remoto - Contenedores»

  2. Crear .devcontainer/devcontainer.json

  3. Reabrir en contenedor

Vim/Neovim:

Configure LSP para usar Docker:

# Run language server in container
docker-compose exec django pylsp

Optimización del rendimiento#

Compartir archivos macOS#

Docker en macOS puede ser lento con bases de código grandes. Optimice con:

django:
  volumes:
    - .:/app:cached  # Use cached consistency mode

modos de consistencia:

  • en caché: las escrituras del host se retrasan en el contenedor (lecturas más rápidas)

  • delegada: las escrituras del contenedor se retrasan en el host (escrituras más rápidas)

  • consistente - Sincrónico (predeterminado, más lento)

Rendimiento de Linux#

Docker en Linux tiene rendimiento nativo, no es necesario realizar ajustes.

Ventanas (WSL2)#

Utilice el backend WSL2 para obtener el mejor rendimiento:

  1. Docker Desktop → Configuración → General → Usar WSL2

  2. Clonar repositorio dentro del sistema de archivos WSL2 (no /mnt/c/)

Ver también#