Skip to content

Installation with Apache and mod_wsgi

The most convenient installation of the Syncer is using Docker, where all dependencies are satisfied automatically. For bare-metal or VM deployments, this guide covers installation with Apache and mod_wsgi.

Base Requirements

dnf install python3.14
dnf install httpd
dnf install python3.14-mod_wsgi

apt install python3.14 apache2 libapache2-mod-wsgi-py3
a2enmod wsgi

Also needed is MongoDB — covered in the MongoDB section below.

Build Requirements (Python Virtual Environment)

The Syncer needs a Python virtual environment. To build it you need the following development packages:

dnf groupinstall "Development Tools"
dnf install httpd-devel
dnf install python3.14-devel

apt install build-essential apache2-dev python3.14-dev

Checkout the Repo and create the Environment

Download the source code first — follow this description and then come back here.

Configure Apache

Create /etc/httpd/conf.d/cmdbsyncer.conf:

<VirtualHost *:80>
    ServerName example.com

    WSGIDaemonProcess cmdbsyncer python-home=/opt/cmdbsyncer/ENV user=apache group=apache threads=5
    WSGIScriptAlias / /opt/cmdbsyncer/app.wsgi
    WSGIPassAuthorization On

    <Directory /opt/cmdbsyncer>
        WSGIProcessGroup cmdbsyncer
        WSGIApplicationGroup %{GLOBAL}
        Require all granted
    </Directory>
</VirtualHost>

Create /etc/apache2/sites-available/cmdbsyncer.conf:

<VirtualHost *:80>
    ServerName example.com

    WSGIDaemonProcess cmdbsyncer python-home=/opt/cmdbsyncer/ENV user=www-data group=www-data threads=5
    WSGIScriptAlias / /opt/cmdbsyncer/app.wsgi
    WSGIPassAuthorization On

    <Directory /opt/cmdbsyncer>
        WSGIProcessGroup cmdbsyncer
        WSGIApplicationGroup %{GLOBAL}
        Require all granted
    </Directory>
</VirtualHost>

Then enable the site: 

a2ensite cmdbsyncer && systemctl reload apache2

HTTPS with SSL Certificate

To run the Syncer over HTTPS, extend the VirtualHost with an SSL block and add a redirect from port 80. Replace the certificate paths with your actual files (e.g. from Let's Encrypt or your CA).

Make sure mod_ssl is installed: dnf install mod_ssl

<VirtualHost *:80>
    ServerName example.com
    Redirect permanent / https://example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName example.com

    SSLEngine on
    SSLCertificateFile      /etc/pki/tls/certs/example.com.crt
    SSLCertificateKeyFile   /etc/pki/tls/private/example.com.key
    # SSLCertificateChainFile /etc/pki/tls/certs/ca-bundle.crt

    WSGIDaemonProcess cmdbsyncer python-home=/opt/cmdbsyncer/ENV user=apache group=apache threads=5
    WSGIScriptAlias / /opt/cmdbsyncer/app.wsgi
    WSGIPassAuthorization On

    <Directory /opt/cmdbsyncer>
        WSGIProcessGroup cmdbsyncer
        WSGIApplicationGroup %{GLOBAL}
        Require all granted
    </Directory>
</VirtualHost>

Make sure mod_ssl is enabled: a2enmod ssl

<VirtualHost *:80>
    ServerName example.com
    Redirect permanent / https://example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName example.com

    SSLEngine on
    SSLCertificateFile      /etc/ssl/certs/example.com.crt
    SSLCertificateKeyFile   /etc/ssl/private/example.com.key
    # SSLCertificateChainFile /etc/ssl/certs/ca-bundle.crt

    WSGIDaemonProcess cmdbsyncer python-home=/opt/cmdbsyncer/ENV user=www-data group=www-data threads=5
    WSGIScriptAlias / /opt/cmdbsyncer/app.wsgi
    WSGIPassAuthorization On

    <Directory /opt/cmdbsyncer>
        WSGIProcessGroup cmdbsyncer
        WSGIApplicationGroup %{GLOBAL}
        Require all granted
    </Directory>
</VirtualHost>

Then enable the site: 

a2ensite cmdbsyncer && systemctl reload apache2

Let's Encrypt

On both distros you can use Certbot to obtain a free certificate automatically:

# RedHat / CentOS
dnf install certbot python3-certbot-apache
# Ubuntu / Debian
apt install certbot python3-certbot-apache

certbot --apache -d example.com

Certbot will update the VirtualHost config and set up automatic renewal.

Apache 2.2 (legacy)

Require all granted was introduced in Apache 2.4. On Apache 2.2 use the old syntax instead:

Order deny,allow
Allow from all

Apache 2.2 is end-of-life — upgrading to 2.4 is strongly recommended.

Key directives explained

Directive Why it is needed
WSGIPassAuthorization On Passes the Authorization HTTP header to the application. Required for REST API authentication — without it, Apache strips the header and all API logins fail.
WSGIDaemonProcess Runs the app in a separate process with its own Python environment.
WSGIApplicationGroup %{GLOBAL} Ensures C extensions (e.g. in the MongoDB driver) work correctly.

MongoDB

Create /etc/dnf.repos.d/mongodb.repo:

[mongodb-org-7.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/dnf/redhat/9/mongodb-org/7.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-7.0.asc

Then install and start MongoDB:

dnf install -y mongodb-org
systemctl enable --now mongod

Follow the official MongoDB guide for Ubuntu, then run:

systemctl enable --now mongod

Troubleshooting

Access Denied in Apache log : SELinux is blocking access. Either disable it or set the correct context:

```bash
chcon -R -t httpd_sys_content_t /opt/cmdbsyncer
setsebool -P httpd_can_network_connect 1
```

API authentication always returns 401 : Check that WSGIPassAuthorization On is set in your VirtualHost config. Without it the Authorization header never reaches the application.

mod_wsgi uses wrong Python version : Verify that the installed mod_wsgi matches your Python version (python3.14-mod_wsgi for Python 3.14). Mismatches cause silent import failures at startup.

MongoDB fails with "Illegal instruction" or does not start : MongoDB 7.0+ requires AVX CPU instructions. If you are running in a virtual machine (e.g. Proxmox), the default CPU type (kvm64) does not expose AVX to the guest even if the host supports it.

Check whether AVX is available inside the VM:
```bash
grep avx /proc/cpuinfo
```

If the output is empty, configure the VM CPU type in Proxmox to expose AVX. Edit the VM config (e.g. `/etc/pve/qemu-server/<vmid>.conf`) and set a CPU type that includes AVX:
```
cpu: x86-64-v2-AES,flags=+avx;+avx2
```
Then restart the VM. Afterwards MongoDB should start normally.