Getting Started

This guide walks through a minimal two-node sync using sync_base and sync_http. No Kubo sidecar is needed. For the Kubo path, see Kubo / IPFS Transport.

Installation

  1. Clone the repository and install the Python dependencies:

    git clone https://github.com/odoostan/odoo-sync
pip install -r addons/sync_base/requirements.txt

  2. Add addons/ to your Odoo addons path:

    # odoo.conf
addons_path = ...,/path/to/odoo-sync/addons

  3. In Odoo, go to Apps and install Sync Base (sync_base) and Sync HTTP (sync_http). Repeat on the second instance.

Note

Install these addons on two Odoo instances in order to test export, delivery and import end-to-end.

Step 1 — Create a Swarm

On Instance A:

  1. Go to Sync ▸ Network ▸ Swarms ▸ New.

  2. Set Name (e.g. My First Swarm) and Network Type: HTTP.

  3. Save — the local gateway node is created automatically and appears in the Nodes tab.

Repeat on Instance B with the same name (the name is local; it does not need to match across instances).

Step 2 — Register a Foreign Node

Each instance needs to know about the other.

On Instance A:

  1. Open the swarm you just created and go to the Nodes tab ▸ New.

  2. Fill in Odoo URL (the base URL of Instance B, e.g. http://odoo-b:8069) and Odoo API Key (an API key generated on Instance B under Settings ▸ Users ▸ API Keys).

  3. Click Test Connection — it should return the remote Odoo version.

Note

The API key is visible only to users in the sync_manager group. The local gateway uses the remote node’s key when posting events, so Instance B can match the key to a local user and enforce its own access rules.

Repeat on Instance B, pointing at Instance A.

Step 3 — Create a Topic

A topic is the central configuration object. It binds a schema to a swarm and controls export/import/delivery behaviour.

  1. Go to Sync ▸ Topics ▸ Topics ▸ New.

  2. Set Name, choose the Schema (create one first — see Step 4 below), and select the Swarm.

  3. Set Export Mode: Instant, Import Mode: Instant, Delivery: Push.

  4. Save — the automation and cron records are created automatically.

Tip

For high-volume models, switch Export Mode or Import Mode to Batch so the three-pass DataLoader processes events in bulk rather than record by record.

Step 4 — Create a Schema

A schema describes the wire format (JSON Schema) and the mapping between JSON paths and Odoo fields.

  1. Go to Sync ▸ Schemas ▸ Schemas ▸ New.

  2. Set Target Model (e.g. res.partner).

  3. Fill Data Schema with a draft-07 JSON Schema for the payload.

  4. Fill Odoo Schema with the mapping. See Odoo Schema for the full operator reference.

  5. Save — ip.schema._check_schemas() validates both schemas and raises a ValidationError if any field path or operator is invalid.

Minimal example for res.partner:

{
  "__root__": { "match": { "ref": "ext_ref" }, "on_miss": "create" },
  "ref":   "ext_ref",
  "name":  "name",
  "email": "email"
}

__root__ with match tells the importer to find-or-update an existing partner by ref, or create one when none is found. See Odoo Schema for the full operator reference.

Step 5 — Trigger a Sync

  1. On Instance A, open a record that matches the topic’s ip.topic.export_domain (leave it empty to match all records of the target model).

  2. Save the record — the Instant automation fires and creates an ip.event with direction='outbound' and routing_state='pending'.

  3. Go to Sync ▸ Content ▸ Events — the event should transition: pending → sending → sent.

  4. On Instance B, go to Sync ▸ Content ▸ Events — you should see a matching inbound event with mapping_state='mapped', and the partner record should exist.

Tip

On a staging or development database, outbound automations are automatically disabled to prevent test data from reaching production peers. Re-enable the automation explicitly if you intend to use this database as a live node. See Configuration for details.

See also