ScrollLaunchpadJobsSearchBlog

Mark Kaharo

Jul 28, 2025 • 8 min read

Odoo Multi-Tenant Setup: Subdomain Per Database with Nginx & Let's Encrypt (Wildcard)

This documentation outlines the process of configuring an Odoo instance to serve multiple databases, each accessible via a unique subdomain (e.g., client1.test.yourdomain.com, client2.test.yourdomain.com). This setup leverages Nginx as a reverse proxy for SSL termination and traffic management, and uses Let's Encrypt for free wildcard SSL certificates.

Target Environment: Debian 12 Server with Odoo already installed and running.

Part 1: Pre-setup Checklist & Information Gathering

Before you begin, ensure you have the following:

  1. Odoo Server: A Debian server with Odoo already installed and running, typically listening on port 8069 (HTTP) and 8072 (Longpolling).

  2. Domain Name: Your main domain (e.g. blackpawinnovations.com).

  3. Target Subdomain: The specific subdomain you want to use for multi-tenancy (e.g., test.blackpawinnovations.com). This documentation will assume *.test.blackpawinnovations.com.

  4. Server IP Address: The public IP address of your Odoo server.

  5. Email Address: An email address for Let's Encrypt notifications (e.g., [email protected]).

  6. Sudo Access: Root or sudo privileges on your Odoo server.

  7. Domain Registrar Account Access (Squarespace is my case): Credentials to log into your Squarespace account to manage DNS settings.

Part 2: Manual Steps (Outside of the Script)

These steps require interaction with your domain registrar (Squarespace) and manual input for Certbot's DNS challenge. The provided bash script cannot fully automate these parts due to security and external service interactions.

2.1 DNS Configuration in Squarespace

You need to configure a wildcard A record and a TXT record (for Certbot's wildcard SSL verification) in your Squarespace domain settings.

  1. Log in to your Squarespace account.

  2. From your Home Menu, click Settings, then click Domains.

  3. Select your main domain: blackpawinnovations.com.

  4. Click on DNS Settings.

  5. Add the Wildcard A Record:

    • Scroll to "Custom Records".

    • Click Add record.

    • Type: A

    • Host: *.test (Squarespace will append .blackpawinnovations.com automatically)

    • Points to: Your Odoo server's public IP address.

    • TTL: Leave as default or set to 300 seconds (for faster propagation).

    • Click Save.

  6. Prepare for Certbot TXT Record (Manual Step during script execution):

    • Keep your Squarespace DNS settings page open. The upcoming script will pause and give you a TXT record to add here.

2.2 Odoo Configuration (dbfilter and proxy_mode)

You must instruct Odoo to verify the hostname for the database name and to trust the reverse proxy.

  1. Connect to your Odoo server via SSH.

  2. Edit the Odoo configuration file:

    sudo nano /etc/odoo.conf

    (Adjust path if your Odoo installation is different, e.g., for source installs, it might be in your Odoo user's home directory ~/.odoorc).

  3. Add or modify the following lines in the [options] section:

    Ini, TOML

    [options]
; ... other Odoo options ...
dbfilter = ^%d$
proxy_mode = True

    • dbfilter = ^%d$: This regular expression tells Odoo to use the first subdomain part (e.g., client1 from client1.test.blackpawinnovations.com) as the database name.

    • proxy_mode = True: This is crucial for Odoo to correctly handle requests coming from Nginx as a reverse proxy (e.g., correctly generate URLs and use the right protocol for HTTPS).

  4. Save the file (Ctrl+X, Y, Enter for Nano).

  5. Restart the Odoo service:

    sudo systemctl restart odoo

    Confirm it restarted without errors:

    sudo systemctl status odoo

2.3 Odoo Database Naming Convention

  • For dbfilter = ^%d$ to work, your Odoo database names must exactly match the subdomains you want to use.

    • If your subdomain will be mycompany.test.blackpawinnovations.com, your Odoo database name should be mycompany.

  • When you first navigate to a new subdomain (e.g., https://newclient.test.blackpawinnovations.com), Odoo will present the database creation screen. Ensure you name the new database exactly as the subdomain (e.g., newclient).

Part 3: Automated Setup Script (Run on your Odoo Server)

This script will install Nginx, configure it as a reverse proxy for Odoo with the correct wildcard SSL setup, and obtain a wildcard SSL certificate from Let's Encrypt using the dns-01 challenge (which you'll interact with manually for a moment).

Save this as setup_odoo_multi_tenant.sh on your Odoo server.

#!/bin/bash

# --- Configuration Variables ---
# IMPORTANT: Customize these variables before running the script
DOMAIN_BASE="blackpawinnovations.com"               # Your main domain
SUBDOMAIN_PREFIX="test"                           # The specific subdomain for multi-tenancy (e.g., 'test' for *.test.yourdomain.com)
FULL_WILDCARD_DOMAIN="*.${SUBDOMAIN_PREFIX}.${DOMAIN_BASE}" # Calculated wildcard domain
BASE_SUBDOMAIN="${SUBDOMAIN_PREFIX}.${DOMAIN_BASE}" # The base domain for the wildcard cert (e.g., test.yourdomain.com)
EMAIL="[email protected]"                    # Your email for Certbot notifications
# ---------------------------------

# --- Basic Setup and Installation ---
echo "--- Starting Odoo Multi-Tenant Setup Script ---"

echo "Updating package lists..."
sudo apt update -y

echo "Installing Nginx..."
sudo apt install -y nginx

echo "Starting and enabling Nginx..."
sudo systemctl start nginx
sudo systemctl enable nginx

echo "Installing Certbot and Nginx plugin (for automatic Nginx configuration post-cert)..."
sudo apt install -y certbot python3-certbot-nginx

# --- Configure UFW Firewall ---
echo "Installing and Configuring UFW firewall..."
sudo apt install -y ufw
sudo ufw allow 'Nginx Full'
sudo ufw delete allow 'Nginx HTTP' # If you previously allowed only HTTP
sudo ufw reload
echo "UFW rules updated."

# --- Nginx Configuration ---
echo "Creating Nginx configuration for ${FULL_WILDCARD_DOMAIN}..."
NGINX_CONF_FILE="/etc/nginx/sites-available/odoo-multi-tenant.conf"

sudo tee "$NGINX_CONF_FILE" > /dev/null <<EOL
# Server block for HTTP (port 80) redirection to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name ${FULL_WILDCARD_DOMAIN} ${BASE_SUBDOMAIN};

    # Redirect all HTTP requests to HTTPS
    return 301 https://\$host\$request_uri;
}

# Server block for HTTPS (port 443)
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name ${FULL_WILDCARD_DOMAIN} ${BASE_SUBDOMAIN};

    # SSL Certificates (managed by Certbot, will be uncommented by Certbot)
    # The paths will be automatically updated by Certbot after successful acquisition
    ssl_certificate /etc/letsencrypt/live/${BASE_SUBDOMAIN}/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/${BASE_SUBDOMAIN}/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    # Odoo specific proxy timeouts and body size
    proxy_read_timeout 720s;
    proxy_connect_timeout 720s;
    proxy_send_timeout 720s;
    client_max_body_size 200m;

    # Proxy buffering settings
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    # Log files for debugging
    access_log /var/log/nginx/odoo-access.log;
    error_log /var/log/nginx/odoo-error.log;

    # Main location block for Odoo's web interface
    location / {
        proxy_pass http://127.0.0.1:8069; # Proxy to Odoo's main HTTP port
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
        proxy_redirect off; # Prevents Odoo from redirecting to internal URLs
    }

    # Location block for Odoo's longpolling (live chat, notifications)
    # This uses a different port and requires WebSocket support
    location /longpolling {
        proxy_pass http://127.0.0.1:8072; # Odoo's default longpolling port
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeouts specific to longpolling
        proxy_read_timeout 3600s;
        proxy_connect_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # Allow Let's Encrypt ACME challenge requests (for http-01, good to keep)
    location ~ /.well-known/acme-challenge {
        allow all;
    }

    # Optional: Deny access to Odoo's database manager via web for security
    # Uncomment the lines below if you manage databases only from the server itself.
    # location ~* /web/database/manager {
    #     deny all;
    # }
    # location ~* /web/database/selector {
    #     deny all;
    # }
}
EOL

echo "Enabling the Nginx configuration..."
sudo ln -s "$NGINX_CONF_FILE" /etc/nginx/sites-enabled/

echo "Testing Nginx configuration..."
sudo nginx -t || { echo "Nginx configuration test failed. Exiting."; exit 1; }

echo "Reloading Nginx..."
sudo systemctl reload nginx

# --- Obtain SSL Certificate using Certbot (DNS-01 Challenge) ---
echo "--- Obtaining Wildcard SSL certificate for ${FULL_WILDCARD_DOMAIN} ---"
echo "ATTENTION: This step requires manual interaction."
echo "Certbot will pause and instruct you to add a TXT record to your DNS."
echo "You will need to go to your Squarespace DNS settings (as outlined in Part 2.1 of the documentation)."
echo "Specifically, you will add a TXT record for '_acme-challenge.${BASE_SUBDOMAIN}' with a specific value."
echo "After adding the record and allowing for DNS propagation (check using tools like mxtoolbox.com/txtlookup.aspx),"
echo "PRESS ENTER to continue Certbot's process."
read -p "Press Enter to start Certbot challenge..."

sudo certbot certonly --nginx --preferred-challenges dns \
  -d "${FULL_WILDCARD_DOMAIN}" -d "${BASE_SUBDOMAIN}" \
  --email "${EMAIL}" --agree-tos --non-interactive

# Check if certbot succeeded
if [ $? -eq 0 ]; then
    echo "SSL certificate obtained successfully."
    echo "Reloading Nginx to apply SSL configuration..."
    sudo systemctl reload nginx
else
    echo "Failed to obtain SSL certificate. Please check Certbot output for errors."
    exit 1
fi

# Test Certbot auto-renewal
echo "Testing Certbot auto-renewal (dry run)..."
sudo certbot renew --dry-run

echo "--- Setup Complete! ---"
echo "Your Odoo server is now configured for multi-tenancy with wildcard SSL for ${FULL_WILDCARD_DOMAIN}."
echo "Remember to name your Odoo databases exactly as the subdomains (e.g., 'client1' for 'client1.${BASE_SUBDOMAIN}')."
echo "You can test by navigating to https://your_database_name.${BASE_SUBDOMAIN}"

Part 4: How to Use the Script

  1. Save the Script: Copy the entire script content above and save it to a file on your Odoo server, for example, setup_odoo_multi_tenant.sh.

    nano setup_odoo_multi_tenant.sh

    Paste the content, save, and exit.

  2. Make it Executable:

    chmod +x setup_odoo_multi_tenant.sh

  3. Customize Variables: Open the script and edit the DOMAIN_BASE, SUBDOMAIN_PREFIX, and EMAIL variables at the top to match your actual domain and email.

    nano setup_odoo_multi_tenant.sh

  4. Run the Script:

    sudo ./setup_odoo_multi_tenant.sh

  5. Follow Certbot Prompts: The script will pause during the Certbot wildcard certificate request.

    • Certbot will provide a TXT record name and value.

    • Go to your Squarespace DNS settings (as described in Part 2.1) and add this specific TXT record.

    • Wait for DNS propagation (crucial!). Use dig TXT _acme-challenge.test.blackpawinnovations.com (replace with your actual name) or an online tool like mxtoolbox.com/txtlookup.aspx to confirm the record is publicly visible.

    • Once confirmed, press Enter in your server's terminal to allow Certbot to continue.

Part 5: Post-Setup Verification

  1. Access Odoo via a Subdomain:

    • Open your web browser and navigate to https://ANY_DATABASE_NAME.test.blackpawinnovations.com (replace ANY_DATABASE_NAME with an actual or desired database name, e.g., mycompany).

    • You should see the Odoo login screen for that specific database, or the database creation screen if it doesn't exist.

    • Verify that the browser shows a secure connection (padlock icon) indicating a valid SSL certificate.

Join Mark on Peerlist!

Join amazing folks like Mark and thousands of other builders on Peerlist.

peerlist.io/

It’s available... this username is available! 😃

Claim your username before it's too late!

This username is already taken, you’re a little late.😐

0

8

0