# Odoo reference

Reference for running Odoo on TurboStack: where the files live, how the service runs, the default ports, and the `odoo.conf` configuration keys. For setup see [Deploy Odoo on TurboStack](deploy.md); for tuning see [Odoo best practices](best-practices.md).

## File layout

Everything lives under your system user's home directory. `~` is that home directory (for example `/var/www/prod/`).

| Path | What it is |
| --- | --- |
| `~/application/odoo/` | Odoo source code and working directory |
| `~/application/odoo/addons/` | Custom modules (add-ons) |
| `~/conf/odoo.conf` | Main configuration file |
| `~/conf/.env` | Environment variables |
| `~/logs/odoo.log` | Application log |

For ownership and permissions, see [Application file layout and permissions](../index.md#file-layout-and-permissions).

## The Odoo service

Odoo runs as a systemd user service, so it needs no root access. The unit lives at `~/.config/systemd/user/application.service`. It starts `odoo-bin` from your pyenv-managed Python and loads its environment from `~/conf/.env`:

```ini
[Unit]
Description=Odoo application (main) for %u
Wants=network-online.target
After=network-online.target
Requires=dbus.socket
StartLimitIntervalSec=0

[Service]
LimitNOFILE=819200
LimitNPROC=819200
LimitMEMLOCK=infinity

TimeoutStartSec=900
Type=simple
WorkingDirectory=%h/application/odoo
EnvironmentFile=%h/conf/.env

ExecStart=%h/.pyenv/shims/python %h/application/odoo/odoo-bin -c %h/conf/odoo.conf
ExecStop=/bin/kill -s TERM $MAINPID
Restart=on-failure
RestartSec=10s
KillSignal=SIGQUIT
StandardOutput=append:%h/logs/odoo.log

[Install]
WantedBy=default.target
```

The high file-descriptor and process limits (`LimitNOFILE`, `LimitNPROC`, `LimitMEMLOCK`) keep Odoo from hitting kernel resource caps under load. `TimeoutStartSec=900` gives module upgrades enough time to finish before systemd considers the start failed. The service restarts on failure after 10 seconds and appends its output to `~/logs/odoo.log`. Manage it with `systemctl --user` - see [How to manage user system services](../../technologies/system-services/manage-user-services.md).

## Default ports

TurboStack fronts Odoo with an Nginx reverse proxy and sets these ports for you. They are advanced overrides; leave them at the defaults unless you have a specific reason to change them.

| Key | Default | What it is |
| --- | --- | --- |
| `odoo.main_port` | `8069` | Main Hypertext Transfer Protocol (HTTP) port |
| `odoo.websocket_port` | `8072` | Websocket / longpolling port |

## Configuration keys

The `workers` count is derived from the server's vCPUs; the other limits are fixed platform defaults. This table is a scannable reference; for when and how to change each value, see [Odoo best practices](best-practices.md).

| Key | Typical value | What it controls |
| --- | --- | --- |
| `workers` | About 3x the vCPU count | Number of Hypertext Transfer Protocol (HTTP) worker processes |
| `max_cron_threads` | `2` | Threads reserved for scheduled (cron) jobs |
| `limit_memory_soft` | Per-worker soft cap | Memory at which a worker is recycled after the current request |
| `limit_memory_hard` | Per-worker hard cap | Memory at which a worker is killed immediately |
| `limit_request` | `8192` | Requests a worker serves before it is recycled |
| `limit_time_cpu` | `3600` | Central Processing Unit (CPU) seconds allowed per request |
| `limit_time_real` | `7200` | Wall-clock seconds allowed per request |
| `limit_time_real_cron` | `86400` | Wall-clock seconds per cron job (24 hours) |
| `db_maxconn` | `64` | Maximum PostgreSQL connections per worker |
| `proxy_mode` | `True` | Required behind the Nginx reverse proxy so Odoo trusts forwarded headers |

### Sizing heuristics

When you do tune `odoo.conf` by hand, size the limits from the server's resources:

- `limit_memory_hard` - about half of total RAM.
- `limit_memory_soft` - about a quarter of total RAM.
- `max_cron_threads` - about one third of the CPU cores (up to half in large setups).
- `limit_time_real_cron` - `0` means unlimited; set it to `86400` (24 hours) to cap long cron jobs.

### Tuning by server size

Copy-pasteable starting points for two common server sizes. Adjust from the heuristics above and measure before changing further.

8 GB RAM / 4 CPU cores:

```ini
workers = 8
limit_memory_hard = 4294967296        ; 4 GB
limit_memory_soft = 2147483648        ; 2 GB
limit_request = 8192
limit_time_cpu = 3600
limit_time_real = 7200
limit_time_real_cron = 0
max_cron_threads = 2
proxy_mode = True
```

48 GB RAM / 12 CPU cores:

```ini
workers = 36
limit_memory_hard = 6442450944        ; 6 GB
limit_memory_soft = 4294967296        ; 4 GB
limit_request = 8192
limit_time_cpu = 3600
limit_time_real = 7200
limit_time_real_cron = 0
max_cron_threads = 4
proxy_mode = True
```

## Related

- [Deploy Odoo on TurboStack](deploy.md)
- [Odoo best practices](best-practices.md)
- [Troubleshooting Odoo](troubleshooting.md)
- [Application file layout and permissions](../index.md#file-layout-and-permissions)
- [How to manage user system services](../../technologies/system-services/manage-user-services.md)