From e78568f22c02467307f0df951a301551733e91cd Mon Sep 17 00:00:00 2001 From: Yhael S Date: Fri, 25 Aug 2023 05:23:47 -0500 Subject: [PATCH] readme updates --- README.md | 88 +++++++++++++++++++++++++++---------------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index ed37d3a..756ff2a 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Note: We always recommend keeping abreast with the official documentation for th **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! -## Quick Setup Guide: +# 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: ``` @@ -67,7 +67,7 @@ For *Windows*, manually add these lines to C:\Windows\System32\drivers\etc\hosts 127.0.0.1 pgadmin.odoocker.test ``` -## The `.env` File +# 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. @@ -96,7 +96,7 @@ DB_PASSWORD=odoo ... ``` -### Environment-based actions: +## 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. 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. @@ -108,18 +108,18 @@ docker-compose down && docker-compose up -d --build && docker-compose logs odoo Here are the descriptions of each of them. -#### 1. Fresh or Restore +### 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. -#### 2. Local: +### 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: +### 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. -#### 4. Testing: +### 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. A `test_DB_NAME` database is automagically created. The `ADDONS_TO_TEST=addon_1` are installed in that fresh DB. @@ -127,10 +127,10 @@ 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: +### 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. -#### 6. Staging: +### 6. Staging: This environment (`APP_ENV=staging`) sets `UPDATE=all`; this allows us to *update* all installed addons at once. It also allows to install new packages before the upgrade through `INIT`. @@ -144,7 +144,7 @@ This will `pull` the latest *Odoo Community, Enterprise, Extra and Custom addons **NOTE: Do not bring down & up again unless you want to perform a whole update again.** -#### 7. Production: +### 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. - Take down previous setup of containers @@ -160,10 +160,10 @@ cp docker-compose.override.production.yml docker-compose.override.yml docker-compose up -d --build && docker-compose logs odoo ``` -## Pro(d) Tips +# Pro(d) Tips The following tips will enhance your developing and production experience. -#### 1. Define the following aliases: +## 1. Define the following aliases: ``` alias odoo='cd odoocker' @@ -174,12 +174,37 @@ alias deploy='docker-compose down && git pull && docker-compose up -d --build && alias logs='docker-compose logs -f --tail 2000 odoo' ``` -#### 2. NEVER run `docker-compose down -v` in Production +## 2. 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**. -#### 3. Colorize your branches +## 3. Odoo Shell +1. Log into the odoo container +``` +docker-compose exec odoo bash +``` +2. Start Odoo shell running: +``` +odoo shell --http-port=8071 +``` + +## 4. Odoo Scaffold +1. Log into the odoo container +``` +docker-compose exec -u root odoo +``` +2. Navigate to custom addons folder inside the container +``` +cd /usr/lib/python3/dist-packages/odoo/custom-addons +``` +3. Create new addons running: +``` +odoo scaffold +``` +- The new addon will be available in the `odoo/custom_addons` folder in this project. + +## 5. Colorize your branches Add the following to `~/.bashrc` ``` # Color git branches @@ -197,35 +222,10 @@ fi unset color_prompt force_color_prompt ``` -#### 4. Odoo Shell -1. Log into the odoo container -``` -docker-compose exec odoo bash -``` -2. Start Odoo shell running: -``` -odoo shell --http-port=8071 -``` +# DB Connection +- Any other Postgres Database Manager can connect to the DB using the `.env` credentials. -#### 5. Odoo Scaffold -1. Log into the odoo container -``` -docker-compose exec -u root odoo -``` -2. Navigate to custom addons folder inside the container -``` -cd /usr/lib/python3/dist-packages/odoo/custom-addons -``` -3. Create new addons running: -``` -odoo scaffold -``` -- The new addon will be available in the `odoo/custom_addons` folder in this project. - -## DB Connection -- Any other Postgres Database Manager con connect to the DB using `.env` credentials. - -### PgAdmin Container +## PgAdmin Container - This project comes with a PgAdmin container which is loaded only in `docker-compose.override.pgadmin.yml`. In order to manage DB we provide a pgAdmin container. In order to bring this up, simply run: @@ -239,7 +239,7 @@ docker-compose -f docker-compose.yml -f docker-compose.override.yml -f docker-co If your instance has pgAdmin, make sure you adapt this to your aliases. -## Deployment Process +# Deployment Process Note: the deployment process is easier & faster with aliases. 1. Backup the production Databases from `/web/database/manager`. @@ -274,5 +274,5 @@ git pull origin main 6. Set `Staging` environment 7. Set `Production` environment -## Final Note +# Footnote This project is based on the [Official Odoo Docker](https://hub.docker.com/_/odoo/) image. We've strived to ensure a seamless integration with the original Docker setup while making necessary customizations to suit our requirements. We encourage contributors and users to frequently refer to the official documentation for foundational concepts and updates. Thank you for your continued support and trust in our project." \ No newline at end of file