Guia de entorno de desarrollo

Odoo Local Dev
con Docker

Configuracion completa paso a paso para Windows, Linux y macOS. Un comando y tu entorno esta listo.

$ docker compose up -d click para copiar

WSL 2 Docker Compose PostgreSQL Odoo VS Code

Configurador

Personaliza los parametros de tu proyecto. Todos los bloques de codigo se actualizan en tiempo real — listos para copiar y pegar directamente en tu terminal.

Nombre del proyecto

sin espacios ni acentos

Version Odoo

Version PostgreSQL

Puerto Odoo

Puerto PostgreSQL

Directorio base

~/proyectos/mi_cliente

db_mi_cliente

odoo_mi_cliente

localhost:8069

Configura tu entorno

Los bloques de codigo se actualizan en tiempo real

Nombre de instancia

Version de Odoo

Edicion

Directorio base

Contenedores: odoo_mi_cliente db_mi_cliente DB: mi_cliente_dev Imagen: odoo:17 Acceso: localhost:8069

Requisitos Previos

Componente	Minimo	Recomendado
RAM	8 GB	16 GB
Almacenamiento	20 GB libres	SSD con 50 GB+
Procesador	64-bit + virtualizacion	4+ cores
Docker	v20+	Ultima estable
Docker Compose	v2+	Ultima estable

Importante

Windows: Virtualizacion debe estar habilitada en BIOS/UEFI (Intel VT-x o AMD-V). macOS: Apple Silicon (M1+) funciona nativamente. Intel Macs necesitan Rosetta en algunos casos.

Instalar Docker

Selecciona tu sistema operativo:

Instalar WSL 2

WSL 2 te da un kernel Linux real dentro de Windows, necesario para Docker.

1Abrir PowerShell como Administrador

Clic derecho en Inicio, Terminal (Administrador)

2Instalar WSL

PowerShell (Admin)

wsl --install

Esto instala WSL 2 con Ubuntu. Reinicia el equipo despues.

3Verificar version

PowerShell
wsl --list --verbose
# Deberias ver tu distro con VERSION 2

Abrir Ubuntu en la Terminal

Tres formas de acceder:

Opcion A: Buscar "Ubuntu" en el menu Inicio.
Opcion B: En Windows Terminal, nueva pestana, seleccionar Ubuntu.
Opcion C: Desde PowerShell:

PowerShell / CMD

wsl

Docker Desktop para Windows

4Descargar e instalar Docker Desktop

Desde docker.com/products/docker-desktop

5Habilitar integracion WSL 2

En Docker Desktop, Settings:
General — "Use WSL 2 based engine" activado
Resources, WSL Integration — Activar tu distro Ubuntu

6Verificar desde WSL

Terminal Ubuntu (WSL)
docker --version
docker compose version
docker run hello-world

Nota

Docker Desktop debe estar corriendo en Windows para que los comandos funcionen dentro de WSL 2.

7Actualizar paquetes de Ubuntu

Terminal Ubuntu (WSL)
sudo apt update && sudo apt upgrade -y

Rendimiento

Trabaja siempre dentro del filesystem de Linux (~/proyectos/...), nunca desde /mnt/c/. El acceso a archivos en /mnt/c/ desde Docker puede ser hasta 10x mas lento.

Docker Engine en Linux

En Linux usas Docker Engine directamente. No necesitas Docker Desktop.

1Instalar Docker Engine (Ubuntu/Debian)

Terminal
# Agregar repositorio oficial de Docker
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker Engine + Compose
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli \
  containerd.io docker-buildx-plugin docker-compose-plugin

2Ejecutar Docker sin sudo

Terminal
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

# Verificar
docker run hello-world

3Habilitar inicio automatico

Terminal
sudo systemctl enable docker
sudo systemctl enable containerd

Rendimiento

Linux es el entorno con mejor rendimiento para Docker — sin capas de virtualizacion. Todo corre nativamente en el kernel.

Docker Desktop para macOS

1Descargar Docker Desktop

Desde docker.com/products/docker-desktop. Selecciona la version para tu chip (Apple Silicon o Intel).

2Instalar y configurar

Arrastra Docker a Applications, abrelo y sigue el asistente. En Settings, Resources, asigna al menos 4 GB de RAM y 2 CPUs.

3Verificar instalacion

Terminal
docker --version
docker compose version
docker run hello-world

Apple Silicon

En Macs con M1/M2/M3/M4, Docker corre las imagenes x86 mediante emulacion Rosetta 2. Si hay issues, habilita "Use Rosetta for x86_64/amd64 emulation" en Docker Desktop, Settings, General.

Editor de Codigo

Recomendamos VS Code por su integracion nativa con WSL y Docker.

1Instalar VS Code

Desde code.visualstudio.com. Marca "Add to PATH" durante la instalacion.

2Extensiones esenciales

Extension	Para que	Solo Windows
WSL	Conectar VS Code al filesystem de Linux	Si
Docker	Gestionar contenedores desde VS Code	No
Python	Soporte para desarrollo Odoo	No
XML Tools	Formateo de vistas Odoo	No

3Abrir proyecto desde terminal

Terminal

cd ~/proyectos/mi_proyecto
code .

En Windows, veras "WSL: Ubuntu" en la esquina inferior izquierda de VS Code, confirmando la conexion remota.

code . no funciona?

Si el comando code no se reconoce dentro de WSL, lo mas probable es que VS Code no fue instalado con "Add to PATH" marcado, o la extension WSL no esta instalada. Reinicia la terminal despues de corregirlo. Ver la seccion Troubleshooting para un diagnostico completo.

Crear el Proyecto

Terminal
# Crear directorio base
mkdir -p ~/proyectos

# Crear proyecto (cambia "mi_cliente" por tu nombre)
cd ~/proyectos
mkdir mi_cliente && cd mi_cliente

# Crear archivos base
touch docker-compose.yml odoo.conf

# Solo para Enterprise:
# touch Dockerfile
# cp /ruta/al/odoo_XX.deb .

# Abrir en VS Code
code .

Estructura del proyecto

mi_cliente/ ├── docker-compose.yml # Definicion de servicios ├── odoo.conf # Configuracion de Odoo ├── Dockerfile # (Solo Enterprise) ├── odoo_XX.deb # (Solo Enterprise) ├── mi_modulo_custom/ # Tus modulos │ ├── __init__.py │ └── __manifest__.py └── otro_modulo/ ├── __init__.py └── __manifest__.py

Nota

El directorio raiz del proyecto se monta como /mnt/extra-addons dentro del contenedor. Cualquier modulo que coloques ahi sera visible para Odoo.

Archivo odoo.conf

Configuracion del servidor Odoo. Crea este archivo en la raiz del proyecto:

odoo.conf
[options]
addons_path = /mnt/extra-addons,/usr/lib/python3/dist-packages/odoo/addons
data_dir = /var/lib/odoo
db_host = db
db_port = 5432
db_user = odoo
db_password = odoo
db_maxconn = 64
admin_passwd = admin
limit_memory_hard = 2684354560
limit_memory_soft = 2147483648
limit_time_cpu = 600
limit_time_real = 1200
max_cron_threads = 1
workers = 0
proxy_mode = False
list_db = True

Parametro	Descripcion
db_host	Nombre del servicio PostgreSQL en docker-compose (ej: `db`)
db_maxconn	Maximo de conexiones simultaneas a la BD
admin_passwd	Contrasena maestra para gestion de bases de datos
workers = 0	Modo single-thread — ideal para desarrollo local
list_db	Permite listar y seleccionar BDs en el login
addons_path	Rutas donde Odoo busca modulos (separadas por coma)

Importante

El valor de db_host debe coincidir exactamente con el nombre del servicio de PostgreSQL en tu docker-compose.yml.

Dockerfile (Solo Enterprise)

Community Edition

Si usas Community Edition, salta esta seccion. No necesitas Dockerfile — se usa la imagen oficial directamente.

Para Enterprise, necesitas una imagen custom con el paquete .deb instalado:

Dockerfile
FROM odoo:17

USER root

# Copiar e instalar el .deb de Enterprise
COPY odoo_17.deb /tmp/odoo_17.deb
RUN dpkg -i /tmp/odoo_17.deb || apt-get install -f -y && \
    rm /tmp/odoo_17.deb

USER odoo

Version	Imagen Base	Archivo .deb	PostgreSQL
15	odoo:15	odoo_15.deb	13 – 14
16	odoo:16	odoo_16.deb	14 – 15
17	odoo:17	odoo_17.deb	15 – 16
18	odoo:18	odoo_18.deb	16 – 17
19	odoo:19	odoo_19.deb	16 – 17

Docker Compose — Community

Template listo para copiar. Usa la imagen oficial de Odoo directamente:

docker-compose.yml — Community
services:
  db:
    image: postgres:16
    container_name: db_mi_cliente
    restart: unless-stopped
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_USER=odoo
      - POSTGRES_PASSWORD=odoo
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    ports:
      - "5432:5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U odoo"]
      interval: 10s
      timeout: 5s
      retries: 5

  odoo:
    image: odoo:17
    container_name: odoo_mi_cliente
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8069:8069"
    volumes:
      - ./:/mnt/extra-addons
      - odoo_web_data:/var/lib/odoo
      - ./odoo.conf:/etc/odoo/odoo.conf
    environment:
      - HOST=db
      - USER=odoo
      - PASSWORD=odoo
      - DB_MAXCONN=64
    command: ["odoo", "--dev=reload,qweb,werkzeug,xml"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8069/web/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

volumes:
  db_data:
    driver: local
  odoo_web_data:
    driver: local

Desglose

Servicio: db (PostgreSQL)

POSTGRES_INITDB_ARGS asegura codificacion UTF-8 con collation C (requisito de Odoo). El healthcheck verifica que PostgreSQL este listo antes de arrancar Odoo.

Servicio: odoo

depends_on con condition: service_healthy garantiza que Odoo no arranque hasta que la BD este lista. El flag --dev=reload,qweb,werkzeug,xml habilita hot-reload.

Volumenes

Volumen	Proposito
./:/mnt/extra-addons	Monta tu directorio como addons de Odoo
odoo_web_data:/var/lib/odoo	Persiste sesiones y filestore
./odoo.conf:/etc/odoo/odoo.conf	Inyecta tu configuracion
db_data:/var/lib/postgresql/data	Persiste la base de datos

Docker Compose — Enterprise

La diferencia clave: usa build: . para construir la imagen con el Dockerfile, en lugar de una imagen directa.

docker-compose.yml — Enterprise
services:
  db:
    image: postgres:16
    container_name: db_mi_cliente
    restart: unless-stopped
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_USER=odoo
      - POSTGRES_PASSWORD=odoo
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    ports:
      - "5432:5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U odoo"]
      interval: 10s
      timeout: 5s
      retries: 5

  odoo:
    build: .                                 # Usa el Dockerfile
    image: odoo_enterprise:17                # Tag personalizado
    container_name: odoo_mi_cliente
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8069:8069"
    volumes:
      - ./:/mnt/extra-addons
      - odoo_web_data:/var/lib/odoo
      - ./odoo.conf:/etc/odoo/odoo.conf
      - ./odoo_17.deb:/mnt/extra-addons/odoo_17.deb
    environment:
      - HOST=db
      - USER=odoo
      - PASSWORD=odoo
      - DB_MAXCONN=64
    command: ["odoo", "--dev=reload,qweb,werkzeug,xml"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8069/web/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 90s

volumes:
  db_data:
    driver: local
  odoo_web_data:
    driver: local

Nota

El start_period de Enterprise (90s) es mayor que Community (60s) porque la imagen con modulos Enterprise tarda mas en inicializar la primera vez.

Levantar el Entorno

1Navegar al proyecto

Terminal

cd ~/proyectos/mi_cliente

2Levantar contenedores

Terminal
# Primera vez (construye imagen si hay Dockerfile)
docker compose up --build

# Ejecuciones posteriores
docker compose up

# En segundo plano (detached)
docker compose up -d

3Verificar estado

Terminal

docker compose ps
# Ambos servicios deben estar Up (healthy)

4Ver logs en tiempo real

Terminal
# Todos los servicios
docker compose logs -f

# Solo Odoo
docker compose logs -f odoo

Acceder a Odoo

Con los contenedores corriendo, abre tu navegador:

Navegador

http://localhost:8069

Crear la base de datos

Campo	Valor Sugerido	Nota
Master Password	admin	Definido en odoo.conf (admin_passwd)
Database Name	mi_cliente_dev	Sin espacios ni caracteres especiales
Email	admin@example.com	Email del administrador
Password	admin	Contrasena del admin
Language	Spanish (GT)	Idioma de la interfaz
Country	Guatemala	Localizacion fiscal

Hot Reload

El flag --dev=reload,qweb,werkzeug,xml en el command del docker-compose habilita la recarga automatica:

Flag	Que hace
reload	Reinicia el servidor cuando detecta cambios en archivos `.py`
qweb	Recarga plantillas QWeb sin reiniciar
werkzeug	Activa el debugger interactivo en el navegador
xml	Recarga vistas XML sin reiniciar

Flujo de trabajo

Cambios en .py — el servidor se reinicia automaticamente. Cambios en XML/QWeb — recarga automatica en la mayoria de casos. Si los cambios en XML no se reflejan, actualiza el modulo: docker compose exec odoo odoo -d mi_cliente_dev -u mi_modulo --stop-after-init

Windows + WSL

El hot-reload depende de inotify (notificaciones del filesystem). Si trabajas desde /mnt/c/, inotify no funciona y el hot-reload falla. Trabaja siempre desde ~/proyectos/ dentro de WSL.

Multiples Instancias

Para correr varios proyectos simultaneamente, cambia puertos, nombres de contenedores y volumenes:

Proyecto	Puerto Odoo	Puerto PG	Acceso
Cliente A	8069:8069	5432:5432	localhost:8069
Cliente B	8070:8069	5433:5432	localhost:8070
Cliente C	8071:8069	5434:5432	localhost:8071
Cliente D	8072:8069	5435:5432	localhost:8072

Que cambiar en cada proyecto

Cambios por instancia
# 1. Nombres de contenedores (unicos)
container_name: db_cliente_b
container_name: odoo_cliente_b

# 2. Puertos (puerto_host:puerto_contenedor)
ports:
  - "5433:5432"          # PostgreSQL
ports:
  - "8070:8069"          # Odoo

# 3. Nombres de volumenes (unicos)
volumes:
  db_data_cliente_b:
    driver: local
  odoo_web_data_cliente_b:
    driver: local

Organizacion

Cada proyecto en su propio directorio: ~/proyectos/cliente_a/, ~/proyectos/cliente_b/, etc. Cada uno con su docker-compose.yml, odoo.conf y modulos.

Comandos Utiles

Gestion de contenedores

Terminal
# Levantar
docker compose up -d

# Detener (conserva datos)
docker compose down

# Detener y BORRAR volumenes (elimina BD y filestore)
docker compose down -v

# Reiniciar un servicio
docker compose restart odoo

# Reconstruir imagen
docker compose up --build -d

# Estado
docker compose ps

Acceso y depuracion

Terminal
# Shell dentro del contenedor Odoo
docker compose exec odoo bash

# Consola PostgreSQL
docker compose exec db psql -U odoo -d mi_base

# Actualizar modulo
docker compose exec odoo odoo -d mi_cliente_dev -u mi_modulo --stop-after-init

# Instalar modulo
docker compose exec odoo odoo -d mi_cliente_dev -i mi_modulo --stop-after-init

Backups

Terminal
# Backup
docker compose exec db pg_dump -U odoo mi_cliente_dev > backup_$(date +%Y%m%d).sql

# Restaurar
cat backup.sql | docker compose exec -T db psql -U odoo mi_cliente_dev

# Limpiar espacio Docker
docker system df
docker system prune

Cuidado

docker compose down -v elimina todo: bases de datos, filestore, sesiones. Solo usalo cuando quieras empezar desde cero. Para detener sin perder datos: docker compose down (sin -v).

Troubleshooting

"port is already allocated"

Otro contenedor o servicio usa el mismo puerto:

Terminal
# Ver que usa el puerto
sudo lsof -i :8069
# o
docker ps -a

# Solucion: detener contenedor conflictivo o cambiar puerto

Odoo no conecta a PostgreSQL

Verifica que db_host en odoo.conf coincida con el nombre del servicio de BD en docker-compose.

Terminal

docker compose ps
docker compose logs db

Hot reload no funciona

Asegurate de que --dev=reload este en el command. En Windows/WSL, verifica que estas trabajando desde el filesystem de Linux (~/), no desde /mnt/c/.

Docker Desktop no inicia (Windows)

PowerShell (Admin)
wsl --shutdown
wsl --update
# Luego reiniciar Docker Desktop

`code .` no funciona en WSL

El comando code dentro de WSL es un wrapper que invoca VS Code de Windows. Si falla, hay cuatro causas habituales:

1VS Code no fue instalado con "Add to PATH"

Reinstala VS Code y marca la casilla "Add to PATH (requires shell restart)". Esto registra el comando code en el PATH de Windows, que WSL hereda automaticamente.

2La extension WSL no esta instalada

Abre VS Code en Windows, ve a Extensions (Ctrl+Shift+X) y busca "WSL" de Microsoft. Sin esta extension, VS Code no puede conectarse al entorno Linux de WSL.

3PATH no heredado correctamente

En algunos casos WSL no hereda el PATH de Windows. Agrega esto a tu ~/.bashrc:

~/.bashrc

# Agregar VS Code al PATH de WSL
export PATH="$PATH:/mnt/c/Users/TU_USUARIO/AppData/Local/Programs/Microsoft VS Code/bin"

Reemplaza TU_USUARIO con tu nombre de usuario de Windows. Luego ejecuta source ~/.bashrc o abre una nueva terminal.

4Verificar interop WSL-Windows

Si nada funciona, verifica que la interoperabilidad este habilitada:

Terminal Ubuntu (WSL)
cat /proc/sys/fs/binfmt_misc/WSLInterop
# Debe mostrar "enabled"

# Si no esta habilitado:
sudo bash -c 'echo 1 > /proc/sys/fs/binfmt_misc/WSLInterop'

`code .` no abre VS Code desde WSL

Este es uno de los problemas mas comunes al configurar WSL por primera vez. El comando code no se reconoce porque VS Code no esta en el PATH de Linux.

1Verificar si code esta en el PATH

Terminal Ubuntu (WSL)

which code
# Si no devuelve nada, code no esta en el PATH

2Solucion rapida: reinstalar desde VS Code en Windows

Abre VS Code en Windows, presiona Ctrl+Shift+P y busca:

VS Code Command Palette

Shell Command: Install 'code' command in PATH

Despues cierra todas las terminales WSL y abri una nueva.

3Si sigue sin funcionar: verificar el PATH manualmente

Terminal Ubuntu (WSL)
# Verificar si la ruta de VS Code esta en el PATH
echo $PATH | grep -i "vscode"

# Si no aparece, agregala manualmente a ~/.bashrc
echo 'export PATH="$PATH:/mnt/c/Users/TU_USUARIO/AppData/Local/Programs/Microsoft VS Code/bin"' >> ~/.bashrc
source ~/.bashrc

Nota

Cambia TU_USUARIO por tu nombre de usuario de Windows. Puedes verificarlo con cmd.exe /c echo %USERNAME% desde WSL.

4Alternativa: abrir desde Windows directamente

Si nada funciona, podes abrir VS Code desde Windows y conectarte a WSL manualmente:

Ctrl+Shift+P en VS Code, luego "WSL: Connect to WSL". Una vez conectado, File, Open Folder y navega a tu proyecto Linux.

Importante

Asegurate de tener la extension WSL instalada en VS Code. Sin ella, no puede conectarse al filesystem de Linux.

Rendimiento lento

Regla de oro

Windows: Trabaja dentro del filesystem Linux (~/proyectos/). macOS: Usa "VirtioFS" en Docker Desktop, Settings, General, File sharing. Linux: Ya tienes rendimiento nativo.

Odoo Local Devcon Docker

Configurador

Configura tu entorno

Requisitos Previos

Instalar Docker

Instalar WSL 2

Abrir Ubuntu en la Terminal

Docker Desktop para Windows

Docker Engine en Linux

Docker Desktop para macOS

Editor de Codigo

Crear el Proyecto

Estructura del proyecto

Archivo odoo.conf

Dockerfile (Solo Enterprise)

Docker Compose — Community

Desglose

Servicio: db (PostgreSQL)

Servicio: odoo

Volumenes

Docker Compose — Enterprise

Levantar el Entorno

Acceder a Odoo

Crear la base de datos

Hot Reload

Multiples Instancias

Que cambiar en cada proyecto

Comandos Utiles

Gestion de contenedores

Acceso y depuracion

Backups

Troubleshooting

"port is already allocated"

Odoo no conecta a PostgreSQL

Hot reload no funciona

Docker Desktop no inicia (Windows)

code . no funciona en WSL

code . no abre VS Code desde WSL

Rendimiento lento

Odoo Local Dev
con Docker

`code .` no funciona en WSL

`code .` no abre VS Code desde WSL