Lewati ke isi

Odoo Local Setup on WSL

Runbook for bringing up a working local Odoo 17 + OpenEduCat + Scola backend on WSL Ubuntu.

Last verified: 2026-04-03

1. Scope

This runbook sets up:

  • PostgreSQL local in WSL
  • Python virtualenv for scola-be
  • Odoo 17 runtime from ../scola-be
  • latest Scola custom modules from ../scola-odoo-module
  • a reproducible config and helper scripts for install/update/run flows

Assumed repo layout:

/home/salfath/scola-fullstack/
├── scola-be
├── scola-fe-v2
└── scola-odoo-module

Path note:

  • Preferred local layout is the Linux filesystem, for example /home/salfath/scola-fullstack/....
  • If your repo is opened from WSL under /mnt/c/Users/..., that is still a valid WSL path to the same files on the Windows disk.
  • The scripts derive sibling repo paths from the current frontend checkout, so either layout works as long as all three repos stay together.

2. What Was Verified

The following was executed successfully on this machine:

  • PostgreSQL 16 installed and online in WSL
  • Odoo Python dependencies installed into scola-be/.venv-wsl
  • clean DB bootstrap for base
  • scola_bundle_core installed successfully on scola_local_clean
  • scola_bundle_dapodik_attendance installed and upgraded successfully on scola_phase6_dap_att_green after enabling optional smart-attendance Python dependencies
  • local Odoo server answered HTTP 200 on http://127.0.0.1:8069/web/login

Runtime note:

  • In this Codex session, data_dir and logfile had to live under /tmp because the agent sandbox cannot let Odoo write freely into sibling repos.
  • For normal local usage outside the sandbox, use the default runtime root scola-be/.local-wsl.

3. Why This Setup Uses Helper Scripts

The bootstrap has a few machine-specific gotchas:

  • System packages, PostgreSQL bootstrap, and runtime directories need root privileges. In normal WSL usage, the scripts now use native sudo.
  • Odoo 17 still expects pkg_resources, so setuptools must stay on a compatible line. The verified pin is setuptools==68.1.2.
  • A plain pip install -r requirements.txt was not fully deterministic on this machine; the helper script follows the exact sequence that worked.

4. One-Time Bootstrap

From scola-fe-v2:

bash scripts/local/bootstrap_odoo_local.sh

This script will:

  1. install PostgreSQL and Odoo system dependencies in WSL
  2. start PostgreSQL
  3. create the local role and database if needed
  4. create scola-be/.venv-wsl
  5. install Python requirements
  6. write scola-be/.local-wsl/odoo-local.conf
  7. initialize base if the target DB is still empty

Useful overrides:

SCOLA_DB_NAME=scola_local_clean \
SCOLA_RUNTIME_ROOT=/home/salfath/scola-fullstack/scola-be/.local-wsl \
bash scripts/local/bootstrap_odoo_local.sh

Optional smart-attendance dependency bootstrap:

SCOLA_INSTALL_SMART_ATTENDANCE_DEPS=1 \
bash scripts/local/bootstrap_odoo_local.sh

Use this when you need SC-ATTEND+, scola_bundle_smart_attendance, or scola_bundle_dapodik_attendance. It installs the face_recognition Python dependency required by scola_hr_attendance.

Sandbox or ephemeral-runtime override:

SCOLA_DB_NAME=scola_local_tmp \
SCOLA_RUNTIME_ROOT=/tmp/scola-odoo-local \
SCOLA_CONFIG_PATH=/tmp/scola-odoo-local/odoo-local.conf \
bash scripts/local/bootstrap_odoo_local.sh

5. Install Scola Modules or Bundles

Example: install the lean modular core bundle.

SCOLA_DB_NAME=scola_local_clean \
bash scripts/local/install_odoo_module.sh scola_bundle_core

Example: install the Dapodik attendance extension after the optional smart-attendance dependency bootstrap.

SCOLA_DB_NAME=scola_phase6_dap_att_green \
bash scripts/local/install_odoo_module.sh scola_bundle_dapodik_attendance

Upgrade modules instead of installing:

SCOLA_DB_NAME=scola_local_clean \
SCOLA_ODOO_MODE=u \
bash scripts/local/install_odoo_module.sh scola_core scola_report_card

6. Run the Local Odoo Server

SCOLA_DB_NAME=scola_local_clean \
bash scripts/local/run_odoo_local.sh

This command does not exit quickly. That is expected: it starts the Odoo server in the foreground and keeps the terminal busy while Odoo is running.

Default URL:

  • http://127.0.0.1:8069

Fast probe:

curl -I http://127.0.0.1:8069/web/login

7. Point Frontend Dev to Local Odoo

npm run dev will use the Vite proxy. In this repo, the proxy fallback is https://be-dev.gcgscola.id unless you override it.

Use the local template:

cp .env.development.local.example .env.development.local

The template sets:

VITE_E2E_ODOO_URL=http://127.0.0.1:8069

Then run:

npm run dev

You should see the Vite console print:

[vite.config] PROXY_TARGET: http://127.0.0.1:8069

8. Config and Paths

Generated config fields come from:

  • Odoo core: ../scola-be
  • OpenEduCat addons: ../scola-be/custom_addons_scola/openeducat
  • OSS addons: ../scola-be/custom_addons_scola/opensource_modules
  • latest Scola addons: ../scola-odoo-module

Default local artifacts:

  • venv: ../scola-be/.venv-wsl
  • runtime root: ../scola-be/.local-wsl
  • config: ../scola-be/.local-wsl/odoo-local.conf
  • default logging: stdout in the terminal running Odoo

9. Known Limitations

  • SC-ATTEND+ face-recognition extras are not part of the default bootstrap path. Enable them with SCOLA_INSTALL_SMART_ATTENDANCE_DEPS=1 only when you need smart-attendance device flows.
  • During scola_bundle_core install, verified non-blocking warnings still appear:
  • issue.media.partner_id unknown field parameter tracking
  • unknown comodel warnings for deferred assessment/attendance extensions
  • Those warnings did not block local startup or scola_bundle_core installation.

10. Troubleshooting

ModuleNotFoundError: No module named 'pkg_resources'

Cause:

  • setuptools is too new for Odoo's expectation.

Fix:

/home/salfath/scola-fullstack/scola-be/.venv-wsl/bin/pip install 'setuptools==68.1.2'

Read-only file system on filestore/logfile

Cause:

  • Runtime root points to a path that the current execution context cannot write.

Fix:

SCOLA_RUNTIME_ROOT=/tmp/scola-odoo-local \
SCOLA_CONFIG_PATH=/tmp/scola-odoo-local/odoo-local.conf \
bash scripts/local/bootstrap_odoo_local.sh

sudo asks for password inside agent session

Cause:

  • The non-interactive session cannot answer sudo prompts.

Fix:

  • Run the helper script from your normal WSL terminal and enter your sudo password when prompted.
  • If you are already root, the script will proceed without sudo.

npm run dev fails with missing @rollup/rollup-linux-x64-gnu

Cause:

  • node_modules was installed from Windows or with a different platform/runtime, so the Linux optional Rollup package was never materialized for WSL.

Fix:

rm -rf node_modules
npm install
npm run dev

After reinstalling in WSL, Vite should start with the local proxy target from .env.development.local.

Python library not installed: face_recognition

Cause:

  • scola_hr_attendance is being installed, but the optional smart-attendance dependency bootstrap was not enabled.

Fix:

SCOLA_INSTALL_SMART_ATTENDANCE_DEPS=1 \
bash scripts/local/bootstrap_odoo_local.sh

Then replay the bundle install or upgrade:

SCOLA_DB_NAME=scola_phase6_dap_att_green \
bash scripts/local/install_odoo_module.sh scola_bundle_dapodik_attendance

Port 8069 is in use by another program

Cause:

  • Another Odoo process is already running on the default local port.

Fix:

ss -ltnp | grep 8069
pkill -f odoo-bin

Or pick another port:

SCOLA_HTTP_PORT=8070 bash scripts/local/bootstrap_odoo_local.sh
SCOLA_HTTP_PORT=8070 bash scripts/local/run_odoo_local.sh

If you change the port, update .env.development.local to match:

VITE_E2E_ODOO_URL=http://127.0.0.1:8070