From 95c1a035995fa0c8223978362249460784fc9183 Mon Sep 17 00:00:00 2001 From: Yhael S Date: Fri, 25 Aug 2023 03:48:41 -0500 Subject: [PATCH] readme updates --- README.md | 261 ++++++++++++++++----------------------------- odoo/entrypoint.sh | 4 +- 2 files changed, 94 insertions(+), 171 deletions(-) diff --git a/README.md b/README.md index d95dff3..2c08073 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Setup +## Setup 1. Clone the repository: ``` git clone git@github.com:yhaelopez/odoocker.git @@ -7,196 +7,123 @@ git clone git@github.com:yhaelopez/odoocker.git ``` cp .env.example .env && cp docker-compose.override.local.yml docker-compose.override.yml ``` -3. Manually add entry to your `hosts` file as below +3. Manually add these domains to your `hosts` file ``` echo '127.0.0.1 erp.odoocker.test' | sudo tee -a /etc/hosts echo '127.0.0.1 pgadmin.odoocker.test' | sudo tee -a /etc/hosts ``` -- For Windows, go to `C:\Windows\System32\drivers\etc\`, and add this line: +- For Windows, go to `C:\Windows\System32\drivers\etc\`, and add: ``` 127.0.0.1 erp.odoocker.test 127.0.0.1 pgadmin.odoocker.test ``` -In order to understand how each environment works, take a look at `odoo/entrypoint.sh`. +## 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. -**Default Master Password:** odoo +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. -## Fresh Environment -This environment will have no database created. -The `env.example` is ready for this stage, no modifications are needed on `.env`. -1. Make sure `APP_ENV=fresh`. -2. Run +Sample `.env` file: ``` -docker-compose up -d --build && docker-compose logs -f odoo -``` -3. Navigate to the `DOMAIN` in your browser. -4. Create Database form will be displayed. -5. Create Fresh DB. -6. Stop the Odoo container: -``` -docker-compose stop odoo -``` -7. Set [`Local`](https://github.com/yhaelopez/odoocker#local-environment) environment. +# Odoo +ODOO_VERSION=16.0 +UPDATE=custom_account_addon +INIT= +LOAD=base,web +WORKERS=2 -## Restore Environment -This environment will have no database created and it's ready to make an import on the production database. -1. Set `APP_ENV=restore`. -2. Run: -``` -docker-compose up -d --build && docker-compose logs -f odoo -``` -3. Navigate to the `DOMAIN` in your browser & Restore the production database -4. Stop the Odoo container: -``` -docker-compose stop odoo -``` -5. Set [`Local`](https://github.com/yhaelopez/odoocker#local-environment) environment. +# Enterprise (GitHub User with access to [Odoo Enterprise](https://github.com/odoo/enterprise) Repo) +GITHUB_USER=yhaelopez +GITHUB_ACCESS_TOKEN=ghp_token -#### If you are in a production server: - -6. Run [`Staging`](https://github.com/yhaelopez/odoocker#staging-environment) environment. -7. Stop the Odoo container: -``` -docker-compose stop odoo -``` -8. Run the [`Production`](https://github.com/yhaelopez/odoocker#production-environment) environment. - -## Full Environment -This environment will initialize a database with `DB_NAME` and install the `INSTALLED_MODULES`. -This allows us to have a fresh production database replica. -1. Make sure `APP_ENV=full`. -2. Make sure `DB_NAME=odoo` or whatever name you want. -3. Run -``` -docker-compose up -d --build && docker-compose logs -f odoo -``` -4. Navigate to the `DOMAIN` in your browser. -5. Log in using the default credentials -``` -Email: admin -Password: admin -``` -6. Stop the Odoo container: -``` -docker-compose stop odoo -``` -7. Set [`Local`](https://github.com/yhaelopez/odoocker#local-environment) environment. - -## Local Environment -This environment will help us install / update the specific modules we are working on. -It's recommended to use this environment after [`Fresh`](https://github.com/yhaelopez/odoocker#fresh-environment), [`Full`](https://github.com/yhaelopez/odoocker#full-environment) or [`Restore`](https://github.com/yhaelopez/odoocker#fresh-environment) environments are run. - -1. Make sure `APP_ENV=local`. -2. Make sure `DB_NAME` is set. -3. Set `UPDATE=module1,module2,module3`. -4. Run: -``` -docker-compose up -d --build && docker-compose logs -f odoo -``` -5. Navigate to the `DOMAIN` in your browser. -6. Start coding! -7. Any change you make to your packages, run: -``` -docker-compose restart odoo && docker-compose logs -f odoo -``` -- If you need to change a .env variable, run: -``` -docker-compose up -d --build && docker-compose logs -f odoo +# Database +ADMIN_PASSWD=odoo +DB_HOST=postgres (container or external host) +DB_PORT=5432 +DB_NAME=my-odoo-db +DB_USER=odoo +DB_PASSWORD=odoo +... ``` -## Debug Environment -This environment will bring up Odoo with `debugpy` library. -It's recommended to use this environment after [`Fresh`](https://github.com/yhaelopez/odoocker#fresh-environment), [`Full`](https://github.com/yhaelopez/odoocker#full-environment) or [`Restore`](https://github.com/yhaelopez/odoocker#fresh-environment) environments are run. -It works the same exact way as [`Local`](https://github.com/yhaelopez/odoocker#local-environment), since it respects any change in `.env` file. +### 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. -1. Make sure `APP_ENV=debug`. -2. Make sure `DB_NAME` is set. -3. Set `UPDATE=module1,module2,module3`. -4. Run: -``` -docker-compose up -d --build && docker-compose logs -f odoo -``` -5. Navigate to the `DOMAIN` in your browser. -6. Mark breakpoints through the code. -7. Start VSCode Debugger -8. Start debugging! -9. Continue coding as if you were in [`Local`](https://github.com/yhaelopez/odoocker#local-environment) +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 `docker-compose down && docker-compose up -d --build && docker-compose logs odoo`. Here are the description of each of them. + +#### *Fresh* or *Restore* +This environment (`APP_ENV=fresh` or `APP_ENV=restore`) will have no database created and it's perfect for setting up a fresh database instance or restoring a production database. + +#### *Local*: +- This environment will strictly follow the `.env` variables with no command-line overwrites. You 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`. + +### *Debug*: +This environment 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. + +#### *Testing*: +- This environment 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. + +*NOTE: Avoid running tests without tags*; this 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. + +#### *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. + +#### *Staging*: +This environment 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`. + +It's highly recommended to use this command to run this environment -## Testing Environment -This environment will help us test the modules we are developing to ensure a safe deployment. -A `test_*` database is automagically created, addons to test get installed, test are filtered and run by their tags. -Odoo will stop after running the tests. -1. Set `APP_ENV=testing`. -2. Set `ADDONS_TO_TEST=addon_1,addon_2`. -3. Set `TEST_TAGS=test_tag_1,test_tag_2` to fitler tests. -4. Run: ``` -docker-compose down && docker-compose up -d --build && docker-compose logs -f odoo +docker-compose down && git pull && docker-compose pull && docker-compose build --no-cache && docker-compose up -d && docker-compose logs -f odoo ``` -## Staging Environment -This environment performs a full update on all installed modules to test if they all can be upgraded at once. -This also allows to install new packages through `INIT` -1. Set `APP_ENV=staging` -2. Set `DB_NAME` to the desired one. -3. Set `INIT` if there are any. -5. Run +This will `pull` the latest *Odoo Community, Enterprise, Extra and Custom addons*, basically, ot upgrades the whole Odoo instance to the newest. Additionally, it will also pull the latest images of the other containers in this project. + +**NOTE: Do not bring down & up again unless you want to perform a whole update again.** + +#### *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 containers ``` -git pull && docker-compose down && docker-compose pull && docker-compose build --no-cache && docker-compose up -d && docker-compose logs -f odoo +docker-compose down ``` -7. Check Odoo continues to work as expected. -8. Change environment immediatly after finish testing. - -**Do not bring down & up again unless you want to perform a whole update again.** - -## Production Environment -This environment has a preset of settings to work in production. Some `.env` variables won't work because are overwritten in the odoo command. - -Let's imagine we are migrating a database from another server. - -1. Set `APP_ENV=production` -2. Set prod `DB_NAME`. -3. Set prod `DB_PASSWORD`. -4. Set prod `ADMIN_PASSWD`. -5. Set prod `DOMAIN` (make sure DNS are pointing to your instance). -6. Run [`Restore`](https://github.com/yhaelopez/odoocker#restore-environment) environment -7. Run [`Staging`](https://github.com/yhaelopez/odoocker#staging-environment) environment. -8. Repace the `docker-compose.override.yml` with `docker-compose.override.production.yml`. -This will bring Let's Encrypt (Nginx-Proxy/Acme-Companion) container +- Repace the `docker-compose.override.yml` with `docker-compose.override.production.yml` to bring `Let's Encrypt` container. ``` cp docker-compose.override.production.yml docker-compose.override.yml ``` -9. Rebuild the containers +- Rebuild the containers ``` -docker-compose down && docker-compose up -d --build && docker-compose logs odoo +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. #### Define the following aliases: ``` alias odoo='cd odoocker' -alias hard-deploy='git pull && docker-compose down && docker-compose pull && docker-compose build --no-cache && docker-compose up -d && docker-compose logs -f odoo' +alias hard-deploy='docker-compose down && git pull && docker-compose pull && docker-compose build --no-cache && docker-compose up -d && docker-compose logs -f odoo' -alias deploy='git pull && docker-compose down && docker-compose pull && docker-compose build && docker-compose up -d && docker-compose logs -f --tail 2000 odoo' - -alias soft-deploy='git pull && docker-compose down && docker-compose up -d --build && docker-compose logs -f --tail 2000 odoo' +alias deploy='docker-compose down && git pull && docker-compose up -d --build && docker-compose logs -f --tail 2000 odoo' alias logs='docker-compose logs -f --tail 2000 odoo' ``` -#### NEVER run -``` -docker-compose down **-v** -``` +#### 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! - -Also, if you do this process several times in a short period of time, you may reach `Let's Encrypt` certificates limits and 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**. #### Colorize your branches Add the following to `~/.bashrc` @@ -216,7 +143,17 @@ fi unset color_prompt force_color_prompt ``` -#### Creating new Odoo Addons +#### Odoo Shell +1. Log into the odoo container +``` +docker-compose exec odoo bash +``` +2. Start Odoo shell running: +``` +odoo shell --http-port=8071 +``` + +#### Odoo Scaffold 1. Log into the odoo container ``` docker-compose exec -u root odoo @@ -231,20 +168,10 @@ odoo scaffold ``` - The new addon will be available in the `odoo/custom_addons` folder in this project. -#### Using 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 +## 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: @@ -258,7 +185,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`. @@ -290,9 +217,5 @@ odoo ``` git pull origin main ``` -6. Set [`Staging`](https://github.com/yhaelopez/odoocker#staging-environment) environment -7. Set `APP_ENV=production` -8. Take down the containers, pull the latest images from docker hub, and rebuild the containers. -``` -docker-compose down && docker-compose up -d --build && docker-compose logs -f odoo -``` +6. Set `Staging` environment +7. Set `Production` environment diff --git a/odoo/entrypoint.sh b/odoo/entrypoint.sh index a343b17..f9ec9bc 100755 --- a/odoo/entrypoint.sh +++ b/odoo/entrypoint.sh @@ -18,9 +18,9 @@ case "$1" in fi if [ ${APP_ENV} = 'full' ] ; then - echo odoo --config ${ODOO_RC} --database=${DB_NAME} --init=${INSTALLED_MODULES} --update= --load=${SERVER_WIDE_MODULES} --log-handler=${LOG_HANDLER} --log-level=${LOG_LEVEL} --load-language=${LOAD_LANGUAGE} --max-cron-threads=${MAX_CRON_THREADS} --limit-time-cpu=3600 --limit-time-real=7200 --workers=0 --without-demo=all + echo odoo --config ${ODOO_RC} --database=${DB_NAME} --init=${INIT} --update= --load=${SERVER_WIDE_MODULES} --log-handler=${LOG_HANDLER} --log-level=${LOG_LEVEL} --load-language=${LOAD_LANGUAGE} --max-cron-threads=${MAX_CRON_THREADS} --limit-time-cpu=3600 --limit-time-real=7200 --workers=0 --without-demo=all - exec odoo --config ${ODOO_RC} --database=${DB_NAME} --init=${INSTALLED_MODULES} --update= --load=${SERVER_WIDE_MODULES} --log-handler=${LOG_HANDLER} --log-level=${LOG_LEVEL} --load-language=${LOAD_LANGUAGE} --max-cron-threads=${MAX_CRON_THREADS} --limit-time-cpu=3600 --limit-time-real=7200 --workers=0 --without-demo=all + exec odoo --config ${ODOO_RC} --database=${DB_NAME} --init=${INIT} --update= --load=${SERVER_WIDE_MODULES} --log-handler=${LOG_HANDLER} --log-level=${LOG_LEVEL} --load-language=${LOAD_LANGUAGE} --max-cron-threads=${MAX_CRON_THREADS} --limit-time-cpu=3600 --limit-time-real=7200 --workers=0 --without-demo=all fi if [ ${APP_ENV} = 'local' ] ; then