Environment Setup

Complete guide to setting up your local development environment.

Prerequisites

Required Software

Software	Version	Purpose
Docker	20.10+	Container runtime
Docker Compose	2.0+	Container orchestration
Git	2.30+	Version control
Text Editor	Any	Code editing (VS Code recommended)

Optional Software

Software	Purpose
pgAdmin	PostgreSQL GUI
DBeaver	Database management
Postman	API testing
VS Code Extensions	Python, Docker, XML

---

Installation

1. Install Docker

Ubuntu/Debian

# Update packages
sudo apt update

# Install prerequisites
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# Add Docker GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker compose version

macOS

# Install Docker Desktop from https://docker.com/products/docker-desktop
# Or use Homebrew:
brew install --cask docker

# Start Docker Desktop application
# Verify installation
docker --version
docker compose version

Windows

1. Install Docker Desktop from https://docker.com/products/docker-desktop
2. Enable WSL 2 backend (recommended)
3. Verify in PowerShell:

   docker --version
   docker compose version
   

2. Install Git

Ubuntu/Debian

sudo apt install -y git
git --version

macOS

brew install git
git --version

Windows

Download from https://git-scm.com/download/win

3. Clone Repository

# Clone the repository
git clone git@github.com:yourorg/odoo15-production.git
cd odoo15-production

# Or with HTTPS
git clone https://github.com/yourorg/odoo15-production.git

---

Project Setup

1. Environment Configuration

# Copy example environment file
cp .env.example .env

# Edit environment variables
nano .env

Required Variables:

# Database
POSTGRES_USER=odoo
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=odoo_test

# Odoo
ODOO_DATABASE=odoo_test
ADMIN_PASSWORD=your_admin_password

# PWA (optional for basic setup)
ODOO_URL=http://odoo:8069
ODOO_DB=odoo_test
ODOO_USERNAME=admin
ODOO_PASSWORD=admin

2. Configuration Files

# Ensure Odoo config is readable
chmod 644 configs/odoo.conf

# Check config file
cat configs/odoo.conf

3. Start Services

# Build and start all containers
docker compose up -d

# Watch logs during startup
docker compose logs -f

# Wait for services to be healthy (about 60 seconds)

4. Initialize Database

# Initialize Odoo database with base module
docker compose exec odoo odoo -i base --stop-after-init -d odoo_test

# Restart Odoo
docker compose restart odoo

5. Verify Installation

# Check all services are running
docker compose ps

# Test endpoints
curl http://localhost:8016  # Odoo
curl http://localhost       # Landing Page (via nginx)
curl http://localhost:8000  # PWA
curl http://localhost:8002  # Docs

# Run health check
./scripts/health-check.sh

---

Access Points

Service	URL	Credentials
Odoo ERP	http://localhost:8016	admin / (from .env)
Landing Page	http://localhost	None (public)
Field PWA	http://localhost:8000	Same as Odoo
Documentation	http://localhost:8002	None
PostgreSQL	localhost:5432	odoo / (from .env)

---

VS Code Setup

Recommended Extensions

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-azuretools.vscode-docker",
    "redhat.vscode-xml",
    "esbenp.prettier-vscode",
    "eamodio.gitlens",
    "streetsidesoftware.code-spell-checker"
  ]
}

Workspace Settings

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "/usr/bin/python3",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.tabSize": 4,
  "files.associations": {
    "*.xml": "xml"
  },
  "[python]": {
    "editor.tabSize": 4
  },
  "[xml]": {
    "editor.tabSize": 4
  }
}

Launch Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Odoo",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}/extra-addons",
          "remoteRoot": "/mnt/extra-addons"
        }
      ]
    }
  ]
}

---

Git Configuration

Initial Setup

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch
git config --global init.defaultBranch main

# Set pull strategy
git config --global pull.rebase false

# Enable colors
git config --global color.ui auto

SSH Key Setup

# Generate SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# Start SSH agent
eval "$(ssh-agent -s)"

# Add key to agent
ssh-add ~/.ssh/id_ed25519

# Copy public key
cat ~/.ssh/id_ed25519.pub
# Add to GitHub: Settings > SSH and GPG keys > New SSH key

# Test connection
ssh -T git@github.com

Git Aliases (Optional)

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --decorate"

---

Database Tools

pgAdmin Setup

1. Install pgAdmin from https://www.pgadmin.org/download/
2. Add server connection:
3. Host: localhost
4. Port: 5432
5. Database: odoo_test
6. Username: odoo
7. Password: (from .env)

DBeaver Setup

1. Install DBeaver from https://dbeaver.io/download/
2. Create new PostgreSQL connection
3. Use same credentials as pgAdmin

Command Line Access

# Connect to database
docker compose exec db psql -U odoo -d odoo_test

# Common commands
\l          # List databases
\dt         # List tables
\d+ table   # Describe table
\q          # Quit

---

Development Workflow

Starting Development

# 1. Pull latest changes
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/my-new-feature

# 3. Start services if not running
docker compose up -d

# 4. Make changes to code
# Edit files in extra-addons/

# 5. Update module in Odoo
docker compose exec odoo odoo -u my_module --stop-after-init -d odoo_test

# 6. Restart Odoo to apply changes
docker compose restart odoo

# 7. Test in browser
# http://localhost:8069

Common Commands

# View logs
docker compose logs -f odoo

# Restart service
docker compose restart odoo

# Stop all services
docker compose down

# Rebuild specific service
docker compose build --no-cache odoo

# Access Odoo shell
docker compose exec odoo odoo shell -d odoo_test

# Access database shell
docker compose exec db psql -U odoo -d odoo_test

---

Troubleshooting Setup

Docker Issues

# Permission denied
sudo usermod -aG docker $USER
# Log out and back in

# Port already in use
sudo lsof -i :8069
# Kill the process or change port in docker-compose.yml

# Out of disk space
docker system prune -a

Database Issues

# Database doesn't exist
docker compose exec db createdb -U odoo odoo_test

# Can't connect
docker compose restart db
docker compose logs db

Module Issues

# Module not found
docker compose restart odoo  # Refresh module list

# Syntax error
docker compose logs odoo | grep -i error

---

Environment Variables Reference

Variable	Description	Default
POSTGRES_USER	Database username	odoo
POSTGRES_PASSWORD	Database password	Required
POSTGRES_DB	Database name	odoo_test
ODOO_DATABASE	Odoo database	odoo_test
ADMIN_PASSWORD	Odoo admin password	Required
ODOO_URL	Odoo URL for PWA	http://odoo:8069
COMPOSE_FILE	Compose files to use	Set in .env

---

Quick Start Checklist

• Docker and Docker Compose installed
• Git installed and configured
• Repository cloned
• .env file created and configured
• docker compose up -d successful
• Database initialized with base module
• Can access Odoo at http://localhost:8016
• Can access Landing Page at http://localhost
• Can access PWA at http://localhost:8000
• Can access Docs at http://localhost:8002
• VS Code extensions installed (optional)
• Database tool configured (optional)