Installing OpenSPP#

This guide walks you through installing OpenSPP on Ubuntu 24.04 or Debian 12 (Bookworm) using the official APT repository hosted on Nexus.

Tip

For development setup instructions, see the Development Setup Guide.

Prerequisites#

Before installing OpenSPP, ensure you have:

  • Ubuntu 24.04 LTS (Noble Numbat) or Debian 12 (Bookworm)

  • 64-bit Intel or AMD CPU (amd64)

  • Minimum 4GB RAM (8GB recommended for production)

  • Minimum 10GB disk space

  • Root access

  • Internet connection for downloading packages

  • Access to https://builds.acn.fr (OpenSPP APT repository)

Step 1: Update system#

First, ensure your system is up to date and install wget and gnupg2:

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y wget gnupg2

Step 2: Install PostgreSQL#

OpenSPP requires PostgreSQL as its database backend. Install and verify by running the commands:

sudo apt-get install -y postgresql postgresql-client
sudo systemctl status postgresql

Step 3: Configure OpenSPP repository#

Add the OpenSPP Public Key and APT repository to your system:

wget -qO - https://builds.acn.fr/repository/apt-keys/openspp/public.key | sudo apt-key add -
echo "deb https://builds.acn.fr/repository/apt-openspp-daily bookworm main" | \
  sudo tee /etc/apt/sources.list.d/openspp.list
sudo apt-get update

Step 4: Install OpenSPP#

Install OpenSPP directly from the repository:

Install OpenSPP package#

sudo apt-get install -y openspp-17-daily

Alternative: Manual download#

If you prefer to download the package manually or the repository is not accessible:

Create a temporary directory where you will then store and run the downloaded package:

mkdir -p ~/openspp-install && cd ~/openspp-install
wget https://builds.acn.fr/repository/apt-openspp/pool/main/o/openspp/openspp_17.0.1+odoo17.0-1_amd64.deb
sudo dpkg -i openspp_17.0.1+odoo17.0-1_amd64.deb

Fix any dependency issues if they occur#

sudo apt-get install -f

The installation will:

  • Create an openspp system user

  • Install files to /opt/openspp/

  • Create data directory at /var/lib/openspp/

  • Create log directory at /var/log/openspp/

  • Install systemd service

  • Install command-line tools in /usr/bin/

Step 5: Configure PostgreSQL#

Create a PostgreSQL user for OpenSPP:

Create the openspp PostgreSQL user#

sudo -u postgres createuser -s openspp

Set password (Optional)#

If you want to use password authentication instead of peer authentication

sudo -u postgres psql -c "ALTER USER openspp WITH PASSWORD 'your_secure_password';"

Step 6: Configure OpenSPP#

Basic configuration#

The main configuration file is located at /etc/openspp/odoo.conf.

  1. Set the admin password (IMPORTANT for security):

Generate a strong password#

openssl rand -base64 32

Copy the generated password

Edit the configuration#

sudo nano /etc/openspp/odoo.conf

Find and update these lines (paste the generated password):

; Security
admin_passwd = YOUR_STRONG_PASSWORD_HERE

  1. Database management settings:

; Database Management
list_db = True          ; IMPORTANT: Set to True to enable database creation via web UI
                        ; Set to False for production (more secure)

  1. Queue job configuration (REQUIRED for OpenSPP):

OpenSPP uses the queue_job module for asynchronous operations. The package includes default configuration, but you may need to adjust it:

; Server-wide modules (queue_job is required)
server_wide_modules = base,web,queue_job

; Performance - workers MUST be > 0 for queue_job to function
workers = 4              ; Set to number of CPU cores - 1 (minimum 2 for queue_job)

[queue_job]
channels = root:2        ; Number of worker channels
; Database connection for job runner (should match main database settings)
jobrunner_db_host =      ; Empty for Unix socket
jobrunner_db_port = 5432
jobrunner_db_user = openspp
jobrunner_db_password = False

Important: Queue jobs will NOT run if workers = 0. Always set workers to at least 2 for production.

  1. Other optional configurations you may want to adjust:

; Memory limits
limit_memory_hard = 4294967296  ; 4GB in bytes
limit_memory_soft = 3221225472  ; 3GB in bytes

; Network
xmlrpc_port = 8069      ; Change if you need a different port
longpolling_port = 8072 ; For real-time features

; Logging
log_level = info        ; Options: debug, info, warning, error, critical

Database configuration#

By default, the package is configured to use Unix socket authentication (peer). This means the openspp system user can connect to PostgreSQL without a password.

If you need to use password authentication:

sudo nano /etc/openspp/odoo.conf

Update:

db_host = localhost
db_password = your_postgresql_password

Step 7: Start OpenSPP service#

Enable the service to start on boot#

sudo systemctl enable openspp

Start the service#

sudo systemctl start openspp

Check service status#

sudo systemctl status openspp

You should see output indicating the service is active and running. Type q to exit this state

Restart the service#

Required to apply any changes to the configuration:

sudo systemctl restart openspp

Step 8: Create your first database#

Option B: Via command line#

Create the database, then restart the service:

sudo -u openspp openspp-server \
    --database=openspp_prod \
    --init=base \
    --stop-after-init
sudo systemctl restart openspp

Step 9: Access OpenSPP#

Once the database is created:

  1. Access the login page at: http://your-server-ip:8069

  2. Login with:

    • Email: The email you provided during database creation

    • Password: The password you set for the admin user

Step 10: Install OpenSPP modules#

After logging in, you'll need to activate the OpenSPP modules:

  1. Navigate to Apps menu

  2. Search and install spp_mis_demo (OpenSPP Demo) or spp_farmer_registry_demo (OpenSPP Farmer Registry Demo)

  3. Restart OpenSPP after installing the demo modules:

    sudo systemctl restart openspp

Note: The queue_job module, which is essential for asynchronous background tasks, is automatically installed as a dependency of the main OpenSPP modules. It is also pre-configured as a server_wide_module, ensuring that background workers can process jobs correctly after a service restart.

Getting Help#

Next steps#

Now that OpenSPP is installed, here are some recommended next steps:

  • Learn to use OpenSPP: Start with the User guide to understand core features.

  • Administer the system: Refer to the Administration for guides on security, maintenance, and troubleshooting.

  • Customize and develop: Explore the Developer guide to learn how to extend the platform.

  • Set Up a pilot program: Follow the From proof of concept to pilot guide to launch a Proof of Concept (PoC).