From ce2bef1bdcbf6d8f72a4ecd1b3fd5a785aac07e4 Mon Sep 17 00:00:00 2001 From: Yhael S Date: Wed, 30 Aug 2023 20:11:07 -0500 Subject: [PATCH] cleanup readme --- README.md | 87 +++++++++++++++++++++++++++---------------------------- 1 file changed, 43 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index fba1d8c..75693a7 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,18 @@ Welcome to Odoocker, a game-changer in the world of Odoo Development and Deployment. This tool is meticulously crafted to revolutionize your experience with Odoo, ensuring simplicity, efficiency, and a top-tier development journey. And while it’s rooted in the principles of the Official Odoo Docker setup, it goes several steps beyond. -**Best of all**, you don't need any prior knowledge of **Odoo** or **Docker** to start your journey with Odoocker. +Whether you're using the Community or Enterprise edition, this Docker solution is tailored just for you. + +**Best part of this?** You don't need any prior knowledge of **Docker**, **Odoo** or any technology that involves this Framework. We stick to Docker philosophy: **Use it, then learn about it.** Feel free to post a Pull Request to continue enhancing this project. ### Why Odoocker Stands Out: +1. 🌐 **Universal:** Suitable for both Odoo Community and Enterprise editions. +2. 📦 **Easy Setup:** Clone, configure `.env` file, and you're ready to deploy. +3. 🔒 **Secure:** Automatic SSL certificate renewal to keep your data safe (for production only). -1. **Minimalistic Server Approach**: In an era where less is more, we keep server clutter at bay. With Odoocker, you'll witness a decluttered server environment, stripped down to the bare essentials. This minimalism ensures optimal resource utilization, leading to faster response times, reduced chances of conflicts, and a smooth-running Odoo instance. - -2. **Usability at its Core**: Odoocker is user-centric. By keeping the interface intuitive and the processes straightforward, we ensure that even newcomers to the Odoo ecosystem can set up and deploy with relative ease. - -3. **Dynamic Yet Simple Configuration**: Customization doesn't have to be complicated. With our `.env` setup, adapting your Odoo instance to your unique needs is a breeze, ensuring you have the flexibility without the fuss. - -4. **Streamlined Development Cycle**: With our intuitive steps and tips, deploying Odoo becomes as simple as 1-2-3. The goal is clear: *to ensure developers do what they love most, code*. - -5. **Clean, Unadulterated Performance**: With a spotlight on a single Odoo instance and a decluttered server, performance optimization is a given. Expect faster load times, smoother operations, and a user experience that’s top-notch. - -In essence, Odoocker isn't just another tool in the developer's arsenal. It's a philosophy. A commitment to clean, efficient, and delightful Odoo development. So, whether you’re a seasoned Odoo veteran or just starting your journey, Odoocker is here to make sure it’s smooth sailing all the way. - -Note: We always recommend keeping abreast with the official documentation for the most detailed and updated insights. Knowledge is power, after all. - -**Note:** While we've aimed to make things simpler, always refer to the official documentation for detailed information and updates. After all, knowledge is power! +In essence, Odoocker isn't just another tool, it's a philosophy. So, whether you’re a seasoned Odoo veteran or just starting your journey, Odoocker is here to make sure it’s smooth sailing all the way. ## Contents @@ -49,9 +40,9 @@ Note: We always recommend keeping abreast with the official documentation for th # Quick Setup Guide: -1. **Clone and Prep**: Get your hands on this wonder-tool in seconds with a simple clone and a few copy commands: +1. **Clone and Configure**: ``` -git clone git@github.com:yhaelopez/odoocker.git +git clone git@github.com:odoocker/odoocker.git cp .env.example .env && cp docker-compose.override.local.yml docker-compose.override.yml ``` 2. **Hosts & Domains**: To ensure everything runs smoothly, remember to add the necessary domains to your hosts file. @@ -68,9 +59,9 @@ For *Windows*, manually add these lines to C:\Windows\System32\drivers\etc\hosts ``` # The `.env` File -The environment variables located in [`.env`](https://github.com/yhaelopez/odoocker/blob/main/.env.example) provide dynamic configurations to Odoo and the project in general. -The [`odoo.conf`](https://github.com/yhaelopez/odoocker/blob/main/odoo/odoo.example.conf) file is generated by the [`odoorc.sh`](https://github.com/yhaelopez/odoocker/blob/main/odoo/odoorc.sh) script based on the environment variables. - +The environment variables located in [`.env`](https://github.com/odoocker/odoocker/blob/main/.env.example) provide dynamic configurations to Odoo and the project in general. +The [`odoo.conf`](https://github.com/odoocker/odoocker/blob/main/odoo/odoo.example.conf) file is generated by the [`odoorc.sh`](https://github.com/odoocker/odoocker/blob/main/odoo/odoorc.sh) script based on the environment variables. +
This file is divided in sections, you most likely are going to focus on the `Main Configuration` section. This provides quick access to project and `odoo.conf` variables. The rest of section are container specific variables for different container. (Note: you may find *repeated variables* like `SUPPORT_EMAIL=${SUPPORT_EMAIL}` which interacts with different containers. This is to explicitly denote in the `.env` file that this variable is being shared through those containers. Sample `.env` file: @@ -85,7 +76,8 @@ DEV_MODE=reload,qweb DOMAIN=erp.odoocker.test # Enterprise (GitHub User with access to Odoo Enterprise [https://github.com/odoo/enterprise] Repo) -GITHUB_USER=yhaelopez +# If not present, Odoo Community will be brought up. +GITHUB_USER=odoocker GITHUB_ACCESS_TOKEN=ghp_token # Database @@ -98,32 +90,36 @@ DB_PASSWORD=odoo LOAD_LANGUAGE=es_MX ... ``` - +
## Environment-based actions: -[`odoo/entrypoint.sh`](https://github.com/yhaelopez/odoocker/blob/main/odoo/entrypoint.sh) file is the gateway for our Odoo container. Depending on the `APP_ENV` and the rest of the environment variables, it determines how to start the Odoo service (like local, testing, production, etc.) with different configurations. +[`odoo/entrypoint.sh`](https://github.com/odoocker/odoocker/blob/main/odoo/entrypoint.sh) file is the gateway for our Odoo container. Depending on the `APP_ENV` and the rest of the environment variables, it determines how to start the Odoo service (like local, testing, production, etc.) with different configurations. +
+In all environments, `odoo.conf` follows the `.env` file variables. Some environments may have command-line parameter to overwrite certain configurations. -All environments receive the whole `.env` file variables. However, some of them have fixed command-line variables specific for each environment. For example, some of them may have `--limit-time-cpu=3600` because some databases are so big that may require a huge amount of seconds. Setting 1 hour ensures any DB can be imported (this can change as needed in the specific project). These values in command line overwrite the ones in the `.env` file. - -**To bring up most of the following environments run**: +**To bring up all the environments run**: +``` +docker-compose up -d --build && docker-compose logs odoo +``` +Restart adding `down`: ``` docker-compose down && docker-compose up -d --build && docker-compose logs odoo ``` -Here are the descriptions of each of them. - ### 1. Fresh or Restore -These environments (`APP_ENV=fresh` or `APP_ENV=restore`) will have no database created and are perfect for setting up a fresh database instance or restoring a production database. +These environments (`APP_ENV=fresh` or `APP_ENV=restore`) will have no database created. Are perfect for setting up a **fresh database** instance or **restoring a production database**. ### 2. Local: This environment (`APP_ENV=local`) will strictly follow the `.env` variables with no command-line overwrites. You'll most likely be using this regularly. Use `DEV_MODE=reload,qweb` to activate hot reload when changing `python` and `xml` files. +
If you prefer to update the packages everytime you restart Odoo container, you can set `UPDATE=module1,module2,module3`. ### 3. Debug: -This environment (`APP_ENV=debug`) works same way as local, but it starts Odoo using the `debugpy` library. Thanks to our [`.vscode/launch.json`](https://github.com/yhaelopez/odoocker/blob/main/.vscode/launch.json), if you are using Visual Studio Code, you start a Debugger session and the container will be aware of your breakpoints and stop wherever you need. This is my favorite environment to work since I use the debugger a lot while developing. +This environment (`APP_ENV=debug`) works same way as local, but it starts Odoo using the `debugpy` library. Thanks to our [`.vscode/launch.json`](https://github.com/odoocker/odoocker/blob/main/.vscode/launch.json), if you are using **Visual Studio Code**, you can start a Debugger session so the container is aware of your breakpoints and stop wherever you need. This is **my favorite** environment to work since I use the debugger a lot while developing. ### 4. Testing: -This environment (`APP_ENV=testing`) is specific for running tests (and will be included in a CI/CD pipeline in a future version). It help us test the modules we are developing to ensure a safe deployment. +This environment (`APP_ENV=testing`) is specific for running tests *(and will be included in a CI/CD pipeline in a future version)*. It help us test the modules we are developing to ensure a safe deployment. +
A `test_DB_NAME` database is automagically created. The `ADDONS_TO_TEST=addon_1` are installed in that fresh DB. Use `TEST_TAGS=test_tag_1` to filter your tests. @@ -131,24 +127,24 @@ Use `TEST_TAGS=test_tag_1` to filter your tests. **NOTE: Avoid running tests without tags**; otherwise, it will trigger tests in all installed addons and we don't want this. For now, let's assume Odoo Community & Enterprise tests passed and only focus on the things you need to test. ### 5. Full: -This environment (`APP_ENV=full`) will install the `INIT` modules in a new or existing `DB_NAME`. This allows us to have a fresh production database replica. +This environment (`APP_ENV=full`) will install the `INIT` modules in a new or existing `DB_NAME`. It allows us to have a fresh production database replica. ### 6. Staging: -This environment (`APP_ENV=staging`) sets `UPDATE=all`; this allows us to *update* all installed addons at once. +This environment (`APP_ENV=staging`) sets `UPDATE=all`; it allows us to **update all installed addons at once**. +
It also allows to install new packages before the upgrade through `INIT`. - +
It's highly recommended to use this command to run this environment - ``` -docker-compose down && git pull && docker-compose pull && docker-compose build --no-cache && docker-compose up -d && docker-compose logs -f odoo +docker-compose down && docker-compose pull && docker-compose build --no-cache && docker-compose up -d && docker-compose logs -f odoo ``` -This will `pull` the latest *Odoo Community, Enterprise, Extra and Custom addons*, basically, it upgrades the whole Odoo instance to the newest. Additionally, it will also pull the latest images of the other containers in this project. +This will `pull` the latest *Odoo Community, Enterprise, Extra and Custom addons*, basically, it **upgrades the whole Odoo instance** to the newest. Additionally, it will also pull the latest images of the other containers in this project. This environment is perfect for deployments. -**NOTE: Do not bring down & up again unless you want to perform a whole update again.** +**NOTE: Do not bring down & up again, unless you want to perform a whole upgrade again.** ### 7. Production: -This is the production environment (`APP_ENV=production`). It ensures no demo data is loaded and debugging is turned off. It also brings up the `Let's Encrypt` container, so you won't worry about `SSL Certificates` anymore! Some `.env` variables are overwritten in this setup. +This environment (`APP_ENV=production`) ensures no demo data is loaded, debugging and dev_mode are turned off. It also brings up the `Let's Encrypt` container, so you won't worry about `SSL Certificates` anymore! Some `.env` variables are overwritten in this setup. - Take down previous setup of containers ``` @@ -158,6 +154,7 @@ docker-compose down ``` cp docker-compose.override.production.yml docker-compose.override.yml ``` +- Make sure the DNS record of your `DOMAIN` is pointing to your server. - Rebuild the containers ``` docker-compose up -d --build && docker-compose logs odoo @@ -167,7 +164,9 @@ docker-compose up -d --build && docker-compose logs odoo The following tips will enhance your developing and production experience. ## 1. Search through all Addons at once: -If you are using `Visual Studio Code` & the Docker Extension is installed, you can open the Odoo Container in the `ROOT_PATH`. There you will find all Odoo `Community Addons`, `Enterprise Addons`, `Extra Addons` and `Custom Addons`. The Extra and Custom addons coming from your project. +If you are using `Visual Studio Code` & the **Docker Extension** is installed, you can open the Odoo Container in the `ROOT_PATH`. There you will find all Odoo `Community Addons`, `Enterprise Addons`, `Extra Addons` and `Custom Addons` in the same folder level. +
+Using the Search Panel will allow you to look at every single reference of what you are looking for in the whole Odoo Instance and not just in your addons. ## 2. Define the following aliases: ``` @@ -182,8 +181,8 @@ alias logs='docker-compose logs -f --tail 2000 odoo' ## 3. NEVER run `docker-compose down -v` in Production ...without having a `tested backed up` database - -Have in mind that dropping volumes will destroy DB data, Odoo Conf & Filestore, *Let's Encrypt certificates, and more!*. If you execute this command several times in `prod` in a short period of time, you may reach the `Let's Encrypt` certificates limit and Odoocker won't be able to generate new ones after **several hours**. +
+Have in mind that dropping volumes will destroy DB data, Odoo Conf & Filestore, *Let's Encrypt certificates, and more!* If you execute this command several times in `prod` in a short period of time, you may reach the `Let's Encrypt certificates limit`` and Odoocker won't be able to generate new ones after **several hours**. ## 4. Odoo Shell 1. Log into the odoo container @@ -243,7 +242,7 @@ And to turn down docker-compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.pgadmin.yml down ``` -If your instance has pgAdmin, make sure you adapt this to your aliases. +If your instance has pgAdmin, make sure you adapt your aliases to this configuration. # Deployment Process Note: the deployment process is easier & faster with aliases.