dalphinloser/odoocker
1
0
Fork 0
mirror of https://github.com/odoocker/odoocker synced 2025-11-04 15:19:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

readme updates

Browse Source
This commit is contained in:
Yhael S
2023-08-25 03:48:41 -05:00
parent 16ccc28b8d
commit 95c1a03599
2 changed files with 94 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
README.md
View File

@@ -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 <addon_name>
```
- 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