`project.yml` — IaC Manifest¶

The single source of truth for each Odoo project. Located at the root of every project directory.

Full Example¶

project:
  name: client1
  author: My Agency
  project_hash: a1b2c3d4e5f6g7h8i9j0...  # auto-generated (64-char SHA-256)
  master_password: "supersecret"           # optional

environments:
  main:
    env_hash: abc123def456789              # auto-generated (15-char)
    server:
      image: odoo
      version: 18.0
      env_type: dev                        # "dev" or "prod"
      users: 5
      ram: auto                            # "auto" or integer GB
      domain: client1.com                  # required for production
      port: 8069                           # dev only
      websecure: true                      # production: Let's Encrypt
      traefik_name: client1-dev            # optional: override Traefik router name
    repositories:                          # optional
      - url: https://github.com/user/custom_addons.git
        branch: 18.0                       # branch name (defaults to server.version)
        rev: v17.0.0                       # or a tag / commit SHA instead of branch
        token: ${GIT_TOKEN_CLIENT1}        # optional — use ${VAR} references for secrets
    preinstall:                            # optional shell commands
      - "npm install -g less"
    postinstall:                           # optional shell commands
      - "pip install odoo-addon-l10n_ar"
    command: -- --dev=reload               # optional custom Odoo command

Project Fields¶

Field	Required	Description
`name`	Yes	Project name (directory name)
`author`	Yes	Person or agency owning the project
`project_hash`	Auto	Unique 64-char SHA-256 identifier
`master_password`	No	Odoo admin password (auto-generated if absent)

Environment Fields¶

Field	Required	Description
`env_hash`	Auto	Unique 15-char identifier
`server.image`	Yes	Docker image (e.g. `odoo`, `custom-build`)
`server.version`	Yes	Odoo version
`server.env_type`	Yes	`dev` or `prod`
`server.users`	Yes	Estimated concurrent users (affects workers)
`server.ram`	Yes	RAM in GB or `auto`
`server.domain`	Prod	Domain name
`server.port`	Dev	Host port for Odoo
`server.websecure`	Prod	Enable Let's Encrypt
`server.proxy_mode`	No	Enable `proxy_mode = True` in odoo.conf
`server.traefik_name`	No	Override Traefik router name
`repositories`	No	List of Git repos to clone into `addons/`
`preinstall`	No	Shell commands before `pip install`
`postinstall`	No	Shell commands after `pip install`
`command`	No	Custom Odoo CLI command

Repository Fields¶

Each entry in repositories supports:

Field	Required	Description
`url`	Yes	Git repository URL
`branch`	No	Git branch (defaults to `server.version` if neither `branch` nor `rev` is set)
`rev`	No	Tag or commit SHA — takes precedence over `branch`
`token`	No	Auth token — use `${VAR}` references (e.g. `${GIT_TOKEN}`) instead of hardcoded values

Token Security¶

Tokens should use ${VAR} syntax to avoid exposing secrets in version control:

repositories:
  - url: https://github.com/user/private_addons.git
    token: ${GIT_TOKEN_CLIENT_X}    # ← resolved from shell env or .env

Resolution order: OS environment variable → per-environment .env file.

Run of repo auth to interactively fill unresolved ${VAR} tokens.

`.project.lock`¶

Automatically generated at the project root by of env init and of env update --git. This file records the exact commit SHA, version, image, and branch/rev info for every cloned repository per environment. It is intentionally tracked in version control to guarantee reproducible deployments.

of env rm <env> automatically removes the environment entry from .project.lock.

`CHANGELOG.md`¶

Auto-generated at the project root, this file tracks key events for auditability:

Added: project creation, new environments, new repositories
Changed: token updates (of repo auth), odoo.conf modifications (of env conf), master password rotation
Removed: environment removal, repository removal

Each entry is grouped under ## YYYY-MM-DD with the appropriate ### subsection.

Repositorios Vacíos¶

Cuando se agrega un repositorio que aún no tiene commits (recién creado en GitHub/GitLab), Odoofly:

Detecta que el clone falla porque el repo está vacío
Clona sin especificar branch (Git crea el directorio local)
Borra la branch por defecto (main) que GitHub asigna automáticamente
Crea la branch del proyecto (ej. 18.0) con git checkout -b
Deja el repo listo para recibir el primer commit

De esta forma, cuando el desarrollador haga su primer git push, la branch 18.0 se crea en el remoto y el proyecto Odoo queda correctamente versionado desde el inicio.

project.yml — IaC Manifest¶