All articles
Getting Started
What is CICDoo Getting started: the onboarding wizard The Dashboard and Infrastructure MapConcepts
Production, staging and development stages Domains, subdomains and SSL Odoo versions and editions (Community vs Enterprise) Workspaces and team collaborationServers
Adding a server Server domains and DNS Using a load balancer Connecting through a jump server Server actions: deploy, logs and charts Deleting a serverProjects & Git
Creating a project Connecting GitHub Project GitHub settings and webhook Connecting GitLab Branches and instances Tagging and filtering projects High availability with app nodes Project environments, extensions and deletionInstances & Console
Creating an instance Restarting, stopping and removing an instance Merging branches between stages Web IDE and remote access SSH access to instances Instance settings explained Deployments and the job queueAgent Tasks
What agent tasks are Setting up agent tasks Running a task and reviewing the result Agent time and top-ups Agent insights and task filtersMonitoring & Backups
Monitoring your instance Backups and restore S3 storage, uploads and bulk backup actions Alert notifications (email and SMS)Workspaces & Permissions
Inviting workspace members Member permissions and resource access A member cannot see or use a resource Audit log and server activityAccount & Security
Two-factor authentication (2FA) Profile and integrations settings Passwords and account recovery Instance security score and checks The Security page: every instance and member at a glanceBilling & Plans
Plans and pricing Upgrading and managing your subscription If a project subscription goes unpaid The channel partner program Onboarding a client as a partnerSupport & Tickets
Opening a support ticket Getting help from the CICDoo teamTroubleshooting
Troubleshooting: cannot connect a server Troubleshooting: a deployment failed Troubleshooting: git push fails with 403 after moving a repository Troubleshooting: my instance is down or slow Troubleshooting: domain or SSL problemsProjects & Git
High availability with app nodes
How to run one production Odoo database on several servers, with a primary project that runs the database, app nodes that serve it and replicas that keep a standby copy.
How it works
High availability lets the production of one Odoo database run on several servers at once. If one server stops answering, visitors are sent to the others.
A cluster is made of projects that run the same code:
- The primary: a project whose production instance runs Odoo and the database. Its database is opened to the app nodes, and to no one else.
- App nodes: other projects, each on a different production server, whose production instance runs Odoo only and uses the primary's database.
- Replicas: app nodes that also keep a standby copy of the primary's database on their own server, ready to take over if the primary is lost.
Visitors use the primary's address. CICDoo points that address at the primary and at every app node that is answering, and checks each node every few minutes. A node that stops answering is taken out of the address until it recovers.
The database itself runs on one server, the primary's. App nodes make the Odoo side redundant. To protect the database as well, add a replica: if the primary's server is lost, you promote the replica and the site carries on from its copy.
Where the settings are
High availability is set per project in the "High Availability" card on the "Advanced" tab of the project settings (open the project's card on the Projects page and click "Settings"). You need permission to change the project's settings.
Note: The "High Availability" card only appears when high availability is available on your account, and the replica role only when replicas are available too. If you do not see them, contact support.
Before you start
- Same code: every project in a cluster must use the same repository, default branch, Odoo version and edition. If Time Machine is on, the pinned commits must match too.
- Different servers: each app node must have its own production server, different from the primary's and from the other nodes'.
- Cloudflare proxy: spreading traffic across the nodes currently works for servers that have the Cloudflare proxy enabled. Use servers in the same region, since every page an app node serves talks to the primary's database.
- Shared filestore: every server in the cluster must mount the same shared storage for the Odoo filestore. Without it, an attachment uploaded through one node is missing on the others, and a visitor who lands on another node is logged out. Ask support if you need help setting this up.
- Database connections: each app node opens its own connections to the primary's database. As you add nodes, raise max_connections in the "PostgreSQL Configuration" of the primary's production instance, in the "Settings" tab of its console.
- How many replicas: each replica needs its own production server. With its default PostgreSQL settings a primary can feed about nine replicas, and each one can hold up to 20 GB of changes on the primary's disk while it is behind.
Setting up the primary
The production instance must use its own bundled database. A project whose production instance points at an external database cannot be a primary.
- Open the project that will run the database and go to its settings, "Advanced" tab.
- In "High Availability", set "Role" to "Primary (app + database)".
- Click "Apply" and confirm the prompt.
The production instance restarts. When it comes back, its database accepts connections from the cluster's app nodes. Connections between servers are encrypted unless your servers share a private network.
On the primary, the card lists its "App nodes" and shows whether the database host has applied the current access list.
Adding an app node
- Create a project for the node as you normally would: same repository and default branch, same version and edition, and a production server of its own. See Creating a project.
- Remove any staging and development instances it has. An app node only runs production; staging and development branches live on the primary project.
- Open the node's settings, "Advanced" tab.
- In "High Availability", set "Role" to "App node (uses a primary's database)".
- In "Database source", pick the primary. Only primaries in this workspace that run the same repository, version and edition are listed.
- Click "Apply" and confirm the prompt.
The node does not start right away. The primary's server first has to let it in, which happens on its next check, usually within five minutes. Until then the card shows "Waiting for the primary to allow this node. It starts automatically, usually within five minutes." The node starts on its own as soon as it is allowed, and a few minutes after it answers, it starts receiving visitors.
Adding a replica
The primary must run PostgreSQL 13 or later, which is the default from Odoo 15, and the replica must use the same PostgreSQL version.
- Prepare a project exactly as for an app node (steps 1 and 2 above).
- Open its settings, "Advanced" tab.
- In "High Availability", set "Role" to "Replica (app node + standby copy of the database)".
- In "Database source", pick the primary.
- Click "Apply" and confirm the prompt.
Joining replaces the replica project's own database with the copy; its old data is moved aside on the server, not deleted. On a large database the first copy takes a while. The primary streams every change to the replica, so the copy is normally only seconds behind. Odoo on a replica serves visitors like on any app node, using the primary's database.
Checking a replica's copy
The replica's "High Availability" card shows the "Database copy" state:
- "Copying": the first copy is being taken.
- "Switching to new primary": another replica was promoted, and this copy is switching over to it. It keeps the data it already has, so this is normally quick.
- "Streaming": the copy is following the primary.
- "Lagging": the copy has fallen more than a few hundred MB behind, or has stopped following for now.
- "Broken": the primary no longer keeps the changes the copy needs.
To fix a broken copy:
- On the replica's "High Availability" card, click "Rebuild copy".
- Confirm that you want to throw the copy away and copy the primary's database again.
A replica uses the primary's PostgreSQL settings. After changing the "PostgreSQL Configuration" of the primary's production instance, restart the replicas.
Promoting a replica when the primary is lost
Promote only when the primary is lost or must be replaced. Changes the old primary made after the copy last caught up are lost. Promotion never happens automatically.
- Open the replica's settings, "Advanced" tab.
- If the card says another replica had a more recent copy at the last check, promote that one instead: you lose fewer changes.
- Click "Promote to primary".
- Type the project name in the prompt to confirm.
The replica's database becomes the cluster's database, the replica becomes the primary, and every other node restarts against it. The site keeps its address. The old primary becomes an app node: when its server comes back it starts without a database of its own, and it receives no visitors until it has restarted that way. Other replicas keep their copy and switch over to the new primary. If one got ahead of the promoted replica, it is rewound to match it, and only if that is not possible does it copy the database again.
Reading from a replica
On Odoo 18 and later, any project in a cluster can send its read-only work to a replica: list and form views, grouped views, reports and exports. Every write still goes to the primary, and a request that turns out to need a write is retried there automatically. This takes load off the primary's database server.
- Open the project's settings, "Advanced" tab.
- In the "High Availability" card, pick the replica in "Read-only queries". A replica can also pick "This replica (its own copy)". "Primary (default)" turns it off.
- Click the "Apply" button next to the field and confirm the prompt.
The project restarts once the replica allows it, usually within five minutes. Reads from a replica can be a moment behind the primary. When a replica falls behind, stops or breaks, CICDoo closes it to readers and Odoo falls back to the primary on its own, without a restart. Readers return to it within about half an hour after it is streaming again.
Point of Sale and writes on a node far from the primary
Every Point of Sale query goes to the primary's database, one after another. On a node in another datacenter, opening a POS session can take a minute instead of a few seconds. Saving a record, clicking a button or logging in works the same way, so those are slow there too. Such a node can send these requests to the primary's site and keep serving the rest.
- Open the node's settings, "Advanced" tab.
- In the "High Availability" card, set "Send to the primary's site" to "Point of Sale", or to "Writes and Point of Sale".
- Click the "Apply" button next to the field and confirm the prompt.
The node restarts. The requests it sends on are then served by the primary and by the nodes that serve everything themselves. With "Writes and Point of Sale", only reads (opening lists, forms and reports) stay on the node, the same reads that go to a read replica, so the node gains most when it reads from a replica on its own side. Every member of the cluster must share its sessions (the session_db module in server_wide_modules), or this option is refused. Set it back to "Nothing: served by this node (default)" to undo.
What changes on an app node
- Its production instance has no database of its own. Its database settings are managed by CICDoo and cannot be changed in the instance's Odoo configuration.
- Scheduled jobs (Odoo crons) run on the primary only.
- Backups are taken on the primary. Back up and restore the cluster's database from the primary project.
- Pushing to an app node's branch does nothing on its own. The cluster is updated from the primary.
- The console of an app node hides the database shell, backups and PostgreSQL settings, which live on the primary. A replica keeps its database shell, which opens its read-only copy.
Deploying updates
Push to the primary's branch as usual. CICDoo then updates the whole cluster in order:
- Each app node is stopped.
- The primary is updated, including any module upgrade, while no other server is using the database.
- Each app node is started again with the new code.
You can follow each step in the "Queue" tab of the instance it runs on. If the primary's update fails, the app nodes are not started again, and their queue entries say why. Fix the problem and deploy again.
Because module upgrades need the database to themselves, the site is unavailable while the primary updates, as it is for a single instance.
Leaving a cluster
- Open the app node's settings, "Advanced" tab.
- Set "Role" back to "Standalone (own database)".
- Click "Apply" and confirm the prompt.
Its production instance stops, because its own database does not hold the cluster's data. Restore a backup into it before starting it again.
A primary cannot be changed while it still has app nodes. Remove the nodes first.
Troubleshooting
- The node keeps waiting to be allowed: check that the primary's production instance is running and that its server is online. The primary has to restart once after becoming a primary before any node is allowed.
- The node starts but Odoo does not come up: open the node's logs. A message saying the primary's database is not initialized means the primary has not finished its first start.
- Uploads or logins do not follow visitors between nodes: the servers are not sharing the filestore. See "Before you start" above.
- A replica stays on Copying: check that the primary's production instance is running. The copy starts once the primary has allowed the replica, and the replica's restart in the "Queue" tab shows its progress or the error.
The Using a load balancer setting on servers is a different feature.
Related: Branches and instances, Using a load balancer, Backups and restore, Instance settings explained.
If you get stuck, open a support ticket from the Tickets page or the chat widget.
Run this on your own servers with CICDoo
Connect a server and link your repository. Deployments, backups and monitoring come set up, and Odoo engineers are a message away.
Still stuck? Open a ticket from the app or talk to an engineer.