Documentation for the Odoox Project

Overview

Odoox is a command-line tool designed to streamline Odoo development workflows. The project contains utilities for managing Odoo modules, configurations, and related development tasks. This document provides an overview of the codebase and detailed explanations of the available features.

---

Table of Contents

• Documentation for the Odoox Project
  • Overview
  • Table of Contents
• Installation
  • Prerequisites
  • Install from sources
• Usage: Getting Started with odoox Tutorial
  • Project Development
    • Step 1: Initialize a New Odoo Project
    • Step 2: Build the Project
    • Step 3: Run the Project
    • Additional Commands
    • Conclusion
  • Module Development
    • Overview
    • Available Options
    • Notes:
    • Terminology:
  • Database Management
    • Overview
    • Available Options
    • Notes:
• Contribute.
  • Project Structure
    • Key Files
  • Modules Overview
    • config.py
    • db.py
    • dockerx.py
    • gitx.py
    • module.py
    • module_init.py
    • odoo_conf.py
    • project.py
  • Future Enhancements

---

Installation

Prerequisites

Before you begin, ensure that you have the following installed:

• Python (3.8 or higher recommended)
• Pipenv (optional, for creating isolated Python environments)
• Docker

---

Install from sources

1. Clone the repository:

   git clone https://github.com/kajande/odoox.git
   cd odoox

2. Install the project and dependencies:

   pip install -e .

3. Verify installation:

   odoox --help

---

Usage: Getting Started with odoox Tutorial

This guide provides a step-by-step tutorial to help you get started with odoox, a command-line tool designed to simplify and accelerate the Odoo development workflow. Follow these instructions to set up, build, and run an Odoo project effortlessly.

---

Project Development

Step 1: Initialize a New Odoo Project

1. Open a terminal and create a new directory for your project:

   mkdir test_project
   cd test_project

2. Set up a Python environment (optional):

   pipenv install

3. Install odoox within the environment:

   • Head to the odoox GitHub repository.
   • Copy the installation command provided in the repository: pip install git+https://github.com/kajande/odoox.git.
   • Paste and execute the command in your terminal.

4. Once installed, initialize the project structure using:

   N.B: Make sure that the directory is empty before running the following command. (Remove any file then put them back later)

   odoox p --init

   This command generates all the necessary files and folders for your project, including:

   • A Dockerfile for building the project.
   • An odoo.conf file for configuring the Odoo instance.
   • A pre-populated Odoo module folder named after your project.

---

Step 2: Build the Project

1. Build the project with a single command:

   odoox build

2. During the build process, observe the logs. You’ll notice that the odoox tool is installed inside the Docker image, enabling you to use it directly within the container.

3. Verify that the build was successful by listing all related images:

   odoox im

   The output will display the project’s image, named after your project and tagged as latest.

---

Step 3: Run the Project

1. Run the project using:

   odoox run

   This command:

   • Starts a PostgreSQL container.
   • Starts an Odoo container connected to the PostgreSQL container.

2. Watch the logs to confirm the base modules are being installed.

3. Access the Odoo application:

   • Use the command:

     odoox url

     This outputs the URL for accessing the Odoo interface. The port includes the Odoo version for easy identification.
   • Open the URL in your browser.

4. Log in to the Odoo interface with the default credentials:

   • Username: admin
   • Password: admin

5. Activate debug mode in the Odoo interface to view additional details, such as the current database and default module.

---

Additional Commands

• Manage containers:

  odoox ps

  Prints the two containers (odoo and postgres) within this project. The two containers are named {project_name}_odoo and {project_name}_pg respectively.

  This means that you cannot recreate new containers because you'll get name conflicts. To do that you'll have to remove the existing ones with odoox rm -og.

  odoox restart -o
  odoox restart -g
  odoox restart -og
  odoox start -o|-g|-og
  odoox stop -o|-g|-og
  odoox rm -o|-g|-og
  
  odoox in -o # gets you inside the odoo container
  odoox in -g # gets you inside the postgres container

  • -o targets the odoo container
  • -g targets the postgres container
  • -og or -go targets both the odoo container and the postgres container

• Get the access URL:

  odoox url

  Prints the URL for accessing the Odoo application.

• List all images:

  odoox im

  Displays all images built for the project.

  odoox im --rm

  Removes current image (tagged latest).

• Tag an image:

  odoox tag <tag>

  Tags the current latest image with a new name, preserving its state.

• Switch to a specific image:

  odoox workon <tag>

  Assigns the latest tag to a specified image, ensuring that odoox run uses it.

---

Conclusion

With just a few commands, odoox streamlines the process of setting up, building, and running Odoo projects. Explore the tool further to discover more features that simplify your Odoo development workflow.

For additional details, check out the documentation or contribute to the project by submitting issues and pull requests.

Module Development

Overview

Odoox simplifies module development with the base command:

odoox m <module> --option

• m: Denotes the subcommand for module-related operations.
• <module>: The name of the target module.
• --option: Specifies the operation to perform.

Available Options

1. Create a Module (Scaffold Base Code):

   odoox m my_module --init

   Initializes the structure for a new module named my_module.

2. Install a Module:

   odoox m my_module -i

   Installs the specified module in the active Odoo database.

   Installs at the same time all dependencies specified in the gitx.conf file. Refer to the example in that file:

   [module11]
   pulluri = https://github.com/odoox-demo-org/repo1.git
   branch =
   track =
   

   where:

   • pulluri specifies the git repository hosting your dependent module
   • [module11] is the name of the your dependent module from that repository
   • branch is the name of the branch your are interested in. (default to main)
   • track is the commit from that branch (default to main)

You may add as many dependencies as you want from same repositories or different repositories.

Note: the repository is downloaded at {project_name/project_name/repos}. Check there!

1. Uninstall a Module:

   odoox m my_module --i

   Uninstalls the module from the active Odoo database.

2. Activate a Module:

   odoox m my_module -a

   Activates the module by installing its data and making it ready for use.

3. Deactivate a Module:

   odoox m my_module --a

   Deactivates the module, effectively disabling it.

4. Update a Module:

   odoox m my_module -u

   Updates the module's data by reloading XML or other configurations.

Notes:

• Restart After Code Changes: If you modify .py files, restart the server with:

  odoox restart -o

• Update After XML Changes: If you modify .xml files, update the module with:

  odoox m my_module -u

Terminology:

• Install vs. Activate:
  • Install: Makes the module available in the database and ready for activation.
  • Activate: Performs the traditional "installation" by loading the module's data and making it usable.

---

Database Management

Overview

Odoox provides a set of commands to simplify interaction with PostgreSQL databases. The base command is:

odoox db <dbname> --options

• db: Denotes the subcommand for database-related operations.
• <dbname>: The name of the database to interact with.
• --options: Specifies the operation to perform.

Available Options

1. Create a Database:

   odoox db <db_name> -c

   Creates a new database named <project_name>_<db_name>.

2. Select a Database:

   odoox db <db_name> -s

   Selects an existing database for further operations. This sets the current database for module commands.

3. Delete a Database:

   odoox db <db_name> -d

   Deletes a specific database, useful in cases of severe database inconsistencies.

4. List All Databases:

   odoox db <db_name> -l

   Lists all databases created under the current project. (TODO)

   Do you want additional database operations ? Run the command odoox in -g to get straight away inside the database and start listing or deleting databases.

Notes:

• Database Name Prefix: Running any odoox db command appends the current project name as a prefix to the database name. For example, executing:

  odoox db test -c

  under a project named proj will create a database named proj_test.

---

Contribute.

Project Structure

odoox/
├── odoox/
│   ├── __init__.py
│   ├── __main__.py
│   ├── config.py
│   ├── db.py
│   ├── dockerx.py
│   ├── gitx.py
│   ├── module.py
│   ├── module_init.py
│   ├── odoo_conf.py
│   ├── project.py
├── .gitignore
├── LICENSE
├── README.md
├── requirements.txt
├── setup.py

Key Files

• odoox/: Contains the main logic of the project.
• setup.py: Installation script for packaging and distribution.
• requirements.txt: Python dependencies required for the project.
• README.md: High-level description and instructions for the tool.

---

Modules Overview

config.py

Purpose: Handles configuration settings for the project.

• Key Features:
  • Load Odoo configurations from files.
  • Provide methods for accessing database and Docker settings.

db.py

Purpose: Provides database utilities for interacting with Odoo databases.

• Key Features:
  • Connect to the PostgreSQL database.
  • Execute queries securely.

dockerx.py

Purpose: Manages Docker containers running Odoo instances.

• Key Features:
  • Restart Docker containers.
  • Fetch container details (e.g., IP address).

gitx.py

Purpose: Facilitates Git operations for Odoo projects.

• Key Features:
  • Clone repositories.
  • Manage Git workflows.

module.py

Purpose: Contains logic for managing Odoo modules.

• Key Features:
  • Copy and rename Odoo modules.
  • Update module configurations.

module_init.py

Purpose: Handles initialization of Odoo modules within the development environment.

• Key Features:
  • Automates the creation of Odoo module scaffolding.

odoo_conf.py

Purpose: Manages the odoo.conf configuration file.

• Key Features:
  • Read and write Odoo configuration files.
  • Update database and path settings.

project.py

Purpose: Manages high-level project settings and operations.

• Key Features:
  • Set up new Odoo projects.
  • Organize project files and directories.

---

Future Enhancements

• Refactor code organisation for better readability and further development
• Add more project management features like commands for setting configurations: username, email, etc.
• Integrate an AI assistant for faster development.

You are invited to contribute !

---

Documentation Last Updated: 2024-12-15