Files
skills/public/hanzo-suite.md

9.5 KiB

Hanzo Suite - Business ERP/CRM Suite (Odoo 18 Fork)

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-commerce.md, hanzo/hanzo-platform.md

Overview

Hanzo Business Suite is a fork of Odoo 18.0 (Community Edition) providing a full-featured open-source ERP/CRM platform tightly integrated with Hanzo AI infrastructure. It includes CRM, e-commerce, warehouse management, project management, billing/accounting, POS, HR, marketing, manufacturing, and 100+ built-in modules. Runs as a Python web application backed by PostgreSQL. Live at team.hanzo.ai and hanzo.team.

Why Hanzo Suite?

  • Full ERP in one platform: CRM, accounting, inventory, HR, e-commerce, POS, project management
  • Odoo 18.0 base: Mature, battle-tested ERP framework with large addon ecosystem
  • AI integration: Positioned for Hanzo AI enhancements on top of Odoo's module system
  • Self-hosted: Docker Compose deployment with PostgreSQL, Traefik reverse proxy
  • Modular: 100+ built-in addons, plus custom addons in /mnt/extra-addons

Tech Stack

  • Language: Python 3.10+ (core framework)
  • Web framework: Werkzeug + custom Odoo HTTP layer
  • ORM: Odoo ORM (custom, PostgreSQL-backed, declarative field definitions)
  • Database: PostgreSQL 16
  • Frontend: Odoo Web Client (JavaScript/OWL framework)
  • Templates: Jinja2 + QWeb (Odoo's XML-based template engine)
  • Container: odoo:18 official Docker image
  • Reverse proxy: Traefik (production)
  • License: LGPL-3.0

OSS Base

Repo: hanzoai/suite. Default branch: main. Fork of Odoo 18.0 Community Edition.

When to use

  • Running internal business operations (CRM, accounting, inventory, HR)
  • E-commerce storefront with integrated warehouse and shipping
  • Project management with time tracking and billing
  • Point-of-sale for retail operations
  • Custom business workflow automation via Odoo modules
  • Financial reporting and accounting

Hard requirements

  1. PostgreSQL 16 database
  2. Python 3.10+ with system dependencies (lxml, Pillow, psycopg2, etc.)
  3. Docker (recommended deployment method)
  4. wkhtmltopdf for PDF report generation (included in Odoo Docker image)

Quick reference

Item Value
Live URL https://team.hanzo.ai / https://hanzo.team
Web port 8069 (mapped to 10017 in dev compose)
Live chat port 8072 (mapped to 20017 in dev compose)
Odoo version 18.0 (final)
Python 3.10+
Database PostgreSQL 16
ORM Odoo ORM (custom)
Default branch main
License LGPL-3.0
Repo github.com/hanzoai/suite

One-file quickstart

Docker Compose (development)

# compose.yaml
services:
 db:
 image: postgres:16
 environment:
 POSTGRES_USER: odoo
 POSTGRES_PASSWORD: "${DB_PASSWORD}"
 POSTGRES_DB: postgres
 volumes:
 - ./postgresql:/var/lib/postgresql/data

 odoo:
 image: odoo:18
 depends_on:
 - db
 ports:
 - "8069:8069"
 - "8072:8072"
 environment:
 HOST: db
 USER: odoo
 PASSWORD: "${DB_PASSWORD}"
 volumes:
 - ./addons:/mnt/extra-addons
 - ./etc:/etc/odoo
# Start
DB_PASSWORD=changeme docker compose up -d

# Access at http://localhost:8069
# First run: create database via web UI

From source

# Clone
git clone https://github.com/hanzoai/suite.git
cd suite

# Install dependencies (use uv for venv)
uv venv
uv pip install -r requirements.txt

# Run
./odoo-bin --addons-path=addons -d mydb

Core Concepts

Architecture

 Traefik (HTTPS)
 |
 team.hanzo.ai / hanzo.team
 |
 +--------------+
 | Odoo 18.0 | :8069 (web)
 | (Python) | :8072 (longpolling/livechat)
 +--------------+
 |
 +--------------+
 | PostgreSQL 16|
 +--------------+

Odoo internals:
 odoo-bin (entrypoint)
 -> odoo.cli.main()
 -> odoo.http (Werkzeug-based HTTP server)
 -> odoo.models (ORM layer)
 -> odoo.fields (field definitions)
 -> odoo.api (environment, decorators)
 -> odoo/addons/* (built-in modules)
 -> /mnt/extra-addons/* (custom modules)

Module System

Odoo's power comes from its modular architecture. Each module is a Python package with:

  • __manifest__.py -- Module metadata (name, version, depends, data files)
  • models/ -- Python ORM model definitions
  • views/ -- XML view definitions (form, tree, kanban, etc.)
  • security/ -- Access control (ir.model.access.csv, record rules)
  • data/ -- Default data (XML/CSV)
  • static/ -- Web assets (JS, CSS, images)
  • controllers/ -- HTTP route handlers

Odoo ORM

The ORM maps Python classes to PostgreSQL tables:

from odoo import models, fields, api

class SaleOrder(models.Model):
 _name = 'sale.order'
 _description = 'Sales Order'

 name = fields.Char(string='Order Reference', required=True)
 partner_id = fields.Many2one('res.partner', string='Customer')
 order_line = fields.One2many('sale.order.line', 'order_id')
 amount_total = fields.Monetary(compute='_compute_total')
 state = fields.Selection([
 ('draft', 'Quotation'),
 ('sale', 'Sales Order'),
 ('done', 'Done'),
 ('cancel', 'Cancelled'),
 ], default='draft')

 @api.depends('order_line.price_subtotal')
 def _compute_total(self):
 for order in self:
 order.amount_total = sum(order.order_line.mapped('price_subtotal'))

Key Built-in Modules

Module Purpose
sale Sales orders and quotations
purchase Purchase orders
stock Warehouse and inventory management
account Accounting and invoicing
crm Customer relationship management
project Project management and tasks
hr Human resources
website Website builder
website_sale E-commerce storefront
point_of_sale Point of sale
mrp Manufacturing
mail Internal messaging and email

Production Deployment

The production compose (compose.prod.yaml) uses:

  • Traefik reverse proxy with automatic Let's Encrypt TLS
  • Domains: team.hanzo.ai and hanzo.team (both routed to same Odoo instance)
  • CSP headers: Scoped to self + team.hanzo.ai + hanzo.team
  • Named volumes: odoo-web-data-prod, odoo-db-data-prod
  • Network: hanzo-network (external Docker network shared with other Hanzo services)
  • Config: Mounted from /etc/hanzo/compose/odoo/files/config
  • Custom addons: Mounted from /etc/hanzo/compose/odoo/files/addons

Directory structure

github.com/hanzoai/suite/
 odoo-bin # Entrypoint script (Python)
 setup.py # Package definition (pip installable as 'odoo')
 setup.cfg # Setup configuration
 requirements.txt # Pinned Python dependencies (per Python version)
 MANIFEST.in # Package manifest
 compose.yaml # Development Docker Compose
 compose.prod.yaml # Production Docker Compose (Traefik + TLS)
 odoo/ # Core framework
 __init__.py # Framework initialization
 release.py # Version info (18.0.0 final)
 api.py # Environment, decorators (@api.depends, @api.model, etc.)
 fields.py # Field type definitions (Char, Integer, Many2one, etc.)
 models.py # Base Model, TransientModel, AbstractModel
 http.py # HTTP layer (Werkzeug-based)
 sql_db.py # Database connection pool
 exceptions.py # UserError, ValidationError, AccessError, etc.
 netsvc.py # Logging and network services
 addons/ # Built-in addon modules (100+)
 cli/ # Command-line interface (server, scaffold, shell, etc.)
 conf/ # Configuration handling
 modules/ # Module loader and registry
 service/ # RPC and WSGI services
 tests/ # Core framework tests
 tools/ # Utility functions (mail, image, misc, etc.)
 upgrade/ # Database upgrade scripts
 osv/ # Legacy ORM compatibility
 addons/ # Custom/extra addons directory (mounted in Docker)
 debian/ # Debian packaging files
 doc/ # Documentation
 setup/ # Setup scripts
 .github/ # Issue/PR templates

Key Python Dependencies

Package Purpose
psycopg2 PostgreSQL adapter
werkzeug HTTP/WSGI framework
lxml XML/HTML processing
Jinja2 Template engine
Pillow Image processing
reportlab PDF generation
passlib Password hashing
gevent Async worker mode
requests HTTP client
cryptography Crypto operations
python-ldap LDAP authentication (optional)

Troubleshooting

Issue Cause Solution
"FATAL: role odoo does not exist" PostgreSQL user not created createuser -s odoo or set POSTGRES_USER in compose
Module not found Addons path not set Add --addons-path=addons,/mnt/extra-addons
"port 8069 already in use" Another Odoo or service running lsof -i :8069 and stop conflicting process
Slow first startup Module installation and asset compilation Normal for first run; subsequent starts are faster
PDF reports blank wkhtmltopdf missing Install via package manager or use Docker image
"database does not exist" No database created Access /web/database/manager to create one
Assets not loading CSS/JS not compiled Clear browser cache; run ./odoo-bin --dev=assets

Environment Variables

# Database connection
HOST=db # PostgreSQL host
USER=odoo # PostgreSQL user
PASSWORD=changeme # PostgreSQL password

# Odoo config file (alternative to env vars)
# /etc/odoo/odoo.conf
  • hanzo/hanzo-commerce.md - Hanzo Commerce (web3 commerce, complementary to Suite)
  • hanzo/hanzo-platform.md - PaaS for deploying Suite instances
  • hanzo/hanzo-database.md - PostgreSQL infrastructure

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: erp, crm, odoo, accounting, inventory, e-commerce, python Prerequisites: Python 3.10+, PostgreSQL 16, Docker (recommended)