Publish on doc.smarterp.et

By default the site is at /docs on your SmartERP address. To serve it from its own domain, such as https://doc.smarterp.et, put a reverse proxy (nginx) in front, map the domain's root onto /docs/, and tell the module its links should start from the root.

A working configuration ships with the module: smarterp_docs/deploy/nginx-doc.smarterp.et.conf.

What you need#

• SmartERP running, with smarterp_docs installed, reachable from the proxy (usually 127.0.0.1:8069).
• A server that can run nginx, with ports 80 and 443 open.
• Control of the DNS for smarterp.et.

Steps#

1. DNS#

Create an A record (and AAAA if you use IPv6) for doc.smarterp.et pointing at the proxy server.

2. Tell Odoo it is behind a proxy#

In odoo.conf:

proxy_mode = True

Restart Odoo. This makes Odoo trust the X-Forwarded-* headers, so addresses and redirects use https and the real host name.

3. Set the base path#

In SmartERP, Settings → Technical → Parameters → System Parameters, create or edit:

The site then writes links like /en/getting-started/... instead of /docs/en/..., which is what a visitor to doc.smarterp.et needs. Leave it at the default (/docs) when you use the site on your main address.

4. Get a certificate#

sudo mkdir -p /var/www/certbot
sudo certbot certonly --webroot -w /var/www/certbot -d doc.smarterp.et

(Start nginx with the port-80 block first, so the challenge can be answered.)

5. Configure nginx#

sudo cp smarterp_docs/deploy/nginx-doc.smarterp.et.conf /etc/nginx/sites-available/doc.smarterp.et
sudo ln -s /etc/nginx/sites-available/doc.smarterp.et /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Edit two things in the file first: the database name in X-Odoo-dbfilter ^smarterp$ and the upstream port if it is not 8069.

6. Check it#

curl -sI https://doc.smarterp.et/            # 302 to /en or /am
curl -s  https://doc.smarterp.et/en | head   # the home page
curl -sI https://doc.smarterp.et/web/login   # 404: the rest of Odoo is not exposed
curl -s  https://doc.smarterp.et/sitemap.xml # every published page

How the mapping works#

location / {
    proxy_pass http://smarterp_odoo/docs/;
    ...
}

Because proxy_pass has a path (/docs/), nginx replaces the matched / with it. So / becomes /docs/, and /en/administration/troubleshooting becomes /docs/en/administration/troubleshooting. Nothing else in Odoo is reachable through this host: /web/login becomes /docs/web/login, which does not exist.

The one extra location, /smarterp_docs/static/, serves images that the documentation ships in the module's static folder.

Choosing the database#

Odoo must know which database to read. Two ways:

• The proxy header (recommended): the X-Odoo-dbfilter ^smarterp$ line in the nginx file, as shipped.
• dbfilter in odoo.conf: dbfilter = ^smarterp$.

If Odoo has a single database, it picks it by itself.

Editing#

Editors work on your main SmartERP address, in the backend, not on the documentation domain. The Edit this page link on a page appears only for a logged-in editor and points at the backend.

Good to know#

• HTTPS everywhere. The nginx file redirects port 80 to 443 and sets HSTS.
• Search engines. /robots.txt allows crawling and /sitemap.xml lists every published page in both languages. Submit the sitemap to Google Search Console and Bing Webmaster Tools.
• Drafts stay private. Unpublished pages return 404 on this host, because visitors there are never logged in as editors.
• Caching. The CSS and JavaScript are inlined, so a page is one request. If you add proxy caching, cache by full URL and not for logged-in users.
• Rate limits. A commented example in the nginx file limits the search endpoints.

Troubleshooting#