Development

This page covers developing and debugging odoo-sync addons when Odoo runs inside Docker alongside the Kubo gateway. It is not a general Odoo development guide.

Two Compose configurations exist side by side:

docker-compose.yml

Production stack. Odoo reads odoo.conf and starts normally.

docker-compose.debug.yml

Debug override. Mounts odoo.debug.conf in place of the normal config, and replaces the Odoo and gateway command entries to wrap each process in debugpy --listen.

Inlining the command in the docker-compose file serves a few purposes:

• Allowing debugpy --listen to wrap the /usr/bin/odoo process.

• Allowing docker compose restart odoo to relaunch odoo.

• Accessing the environment variables defined in .env.

This command bypasses the official docker image’s entrypoint.sh and its options parsing / argument injection oddities.

Note

Changing the docker-compose command will only take effect after recreating the container.

---

Cheatsheet

Docker

docker compose restart odoo                 # restart only Odoo
docker compose up -d                        # recreate changed containers
docker compose up --force-recreate          # recreate all containers
docker compose up --build                   # rebuild all images
docker compose exec -it <svc> /bin/bash     # interactive shell in any service
docker compose logs -f <svc>                # follow logs
docker compose stop                         # stop all containers

Odoo

# Update modules targeted by -u in the docker-compose command
docker compose restart odoo

# Update specific module (if not targeted)
docker compose run --rm odoo /usr/bin/odoo \
    -d postgres --db_host=db -r odoo -w odoo \
    -u sync_base --stop-after-init
docker compose restart odoo

Warning

-u does not reload mounted Python files unless dev=all is set in the odoo-bin options. Always follow a manual module update with a container restart.

IPFS

# Publish a raw CID string on a test topic
echo -n "QmFakeCid" | docker compose exec -T ipfs ipfs pubsub pub test.topic

# Add a JSON file to IPFS and publish its CID
echo '{"model":"res.partner","name":"Stan"}' \
    | docker compose exec -T ipfs ipfs add -Q \
    | xargs -I{} sh -c \
        'echo -n "{\"cid\": \"{}\"}" | docker compose exec -T ipfs ipfs pubsub pub test.topic'

# Re-run the swarm setup script (only runs automatically on volume creation)
docker compose exec ipfs /container-init.d/001-setup-swarm.sh

# Call the Kubo API directly over HTTP
curl -X POST http://127.0.0.1:5001/api/v0/id                         # node id (debug conf)
curl -X POST -F file=@myfile.txt "http://127.0.0.1:5001/api/v0/add"  # add file (debug conf)

---

Remote Debugging

The debug setup uses debugpy to expose attach points into the running containers.

Docker Override

Copy docker-compose.debug.yml to docker-compose.override.yml next to it. Docker Compose automatically merges override files, opening the debug ports without modifying the main compose file.

This exposes three attach ports:

Port	Process
5678	Odoo web worker
5679	Odoo interactive shell
5680	Gateway daemon

For the Odoo shell, start the debug server manually:

docker compose exec odoo python3 -m debugpy \
    --listen 0.0.0.0:5679 \
    /usr/bin/odoo shell -d postgres --db_host=db -r odoo -w odoo

For remote access, open an SSH tunnel:

ssh -L 5678:127.0.0.1:5678 user@my.domain

VSCode

Add the following configuration to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "ODOO_ATTACH",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "justMyCode": false,
      "subProcess": true,
      "pathMappings": [
        {
          "remoteRoot": "/usr/lib/python3/dist-packages/odoo",
          "localRoot": "<path-to-odoo-community>/odoo"
        },
        {
          "remoteRoot": "/usr/lib/python3/dist-packages/addons",
          "localRoot": "<path-to-odoo-community>/addons"
        },
        {
          "remoteRoot": "/mnt/extra-addons",
          "localRoot": "<path-to-odoo-sync>/addons"
        },
        {
          "remoteRoot": "/app",
          "localRoot": "<path-to-odoo-sync>/gateway"
        }
      ]
    }
  ]
}

Change port to 5679 for the Odoo shell or 5680 for the gateway.

---

Environment Reset

Danger

You have entered the danger zone. Consider yourself warned.

# Soft reset — destroy containers, keep named volumes (db, filestore, metrics)
docker compose down

# Hard reset — destroy named volumes
docker compose down -v

# Nuke reset — wipe mounted Kubo volumes (node identity and data blocks)
sudo rm -rf /var/ipfs_data/data/*     # Kubo data blocks, keys, configs
sudo rm -rf /var/ipfs_data/staging/*  # manual staging exports

Warning

The nuke reset deletes the node’s Ed25519 identity keypair stored in /var/ipfs_data/data/. The node will generate a new PeerID on next boot and must be re-registered in Odoo as a new ip.peer record.