Install Horilla on AlmaLinux: Step-by-Step Guide

Horilla is an open source human resource management system built with Python and Django, and AlmaLinux provides a stable enterprise Linux base for hosting it. A typical installation involves preparing the server, installing Python and PostgreSQL, cloning the Horilla source code, configuring environment settings, running database migrations, and serving the application through Gunicorn and Nginx.

TLDR: To install Horilla on AlmaLinux, the administrator prepares the system packages, installs PostgreSQL and Python dependencies, then downloads Horilla from its official repository. After configuring the database and application environment, migrations are applied and a superuser account is created. For production use, Horilla should run behind Nginx with Gunicorn managed by systemd.

Prerequisites

Before installation begins, the server should have a clean AlmaLinux installation, preferably AlmaLinux 9, with root or sudo access. The system should also have a valid domain name if Horilla will be exposed publicly. Although Horilla can be tested locally, a production deployment is more reliable when PostgreSQL, Nginx, and a dedicated application user are used.

Operating system: AlmaLinux 8 or 9
Access: Root or sudo-enabled user
Database: PostgreSQL

Web server: Nginx
Application server: Gunicorn
Runtime: Python 3 and virtual environment

Image not found in postmeta

Step 1: Update the AlmaLinux System

The administrator should first update all installed packages. This reduces the risk of dependency conflicts and ensures security patches are applied before Horilla is installed.

sudo dnf update -y

After the update completes, installing a few essential utilities is recommended. These tools are commonly required for Python packages, source compilation, and repository management.

sudo dnf install -y git curl wget vim gcc gcc-c++ make

Step 2: Install Python and Development Packages

Horilla is a Django-based application, so Python and related build libraries are required. AlmaLinux usually ships with Python 3, but the required development headers should still be installed.

sudo dnf install -y python3 python3-pip python3-devel

The administrator can verify the installed versions with:

python3 --version
pip3 --version

If the server runs an older Python version that is not compatible with the current Horilla release, a newer Python version may need to be installed from approved repositories or built separately. For most current AlmaLinux 9 environments, the default Python version is suitable.

Step 3: Install and Configure PostgreSQL

PostgreSQL is a strong choice for production Django applications. It provides reliability, scalability, and better data integrity than lightweight databases used for testing.

sudo dnf install -y postgresql-server postgresql-contrib postgresql-devel

Once installed, the database cluster must be initialized:

sudo postgresql-setup --initdb

Then PostgreSQL should be enabled and started:

sudo systemctl enable --now postgresql

The administrator can confirm that PostgreSQL is running:

sudo systemctl status postgresql

Create the Horilla Database and User

A separate PostgreSQL database and user should be created for Horilla. This keeps application data isolated and improves security.

sudo -u postgres psql

Inside the PostgreSQL shell, the following commands create the database and user. The password should be replaced with a strong secret.

CREATE DATABASE horilla_db;
CREATE USER horilla_user WITH PASSWORD 'StrongPasswordHere';
ALTER ROLE horilla_user SET client_encoding TO 'utf8';
ALTER ROLE horilla_user SET default_transaction_isolation TO 'read committed';
ALTER ROLE horilla_user SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE horilla_db TO horilla_user;
\q

Step 4: Create a Dedicated Horilla User

Running the application as root is not recommended. A dedicated system user limits risk and makes it easier to manage files, permissions, and services.

sudo useradd -m -r -s /bin/bash horilla

The application can be installed under the dedicated user’s home directory:

sudo mkdir -p /opt/horilla
sudo chown horilla:horilla /opt/horilla

Step 5: Download Horilla

The administrator should switch to the Horilla user and clone the official Horilla repository. The repository URL may vary depending on the official project location, but the common open source repository is hosted on GitHub.

sudo -iu horilla
cd /opt/horilla
git clone https://github.com/horilla-opensource/horilla.git app
cd app

If a specific release is required, the administrator may check available tags and switch to a stable version instead of using the latest branch.

git tag
git checkout <version-tag>

Image not found in postmeta

Step 6: Create a Python Virtual Environment

A Python virtual environment keeps Horilla dependencies separate from system packages. This is especially important on enterprise Linux systems where system Python packages may be managed by the operating system.

python3 -m venv venv
source venv/bin/activate

Next, the administrator should upgrade pip and install the required Python packages:

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

If the installation reports missing PostgreSQL build dependencies, the administrator should confirm that postgresql-devel, gcc, and python3-devel are installed.

Step 7: Configure Horilla Environment Settings

Horilla needs database settings, secret keys, allowed hosts, and other environment values. The project may include an example environment file. If present, it can be copied and edited:

cp .env.example .env
vim .env

If no example file exists, the administrator should consult the project documentation and create the required variables manually. A typical production configuration may include values similar to the following:

DEBUG=False
SECRET_KEY=ReplaceWithLongRandomSecretKey
ALLOWED_HOSTS=example.com,www.example.com,server_ip_address

DB_ENGINE=django.db.backends.postgresql
DB_NAME=horilla_db
DB_USER=horilla_user
DB_PASSWORD=StrongPasswordHere
DB_HOST=127.0.0.1
DB_PORT=5432

The SECRET_KEY must be unique and private. The ALLOWED_HOSTS value should include the domain name or IP address used to access Horilla. In production, DEBUG should remain disabled.

Step 8: Run Migrations and Create an Admin User

Database migrations create the tables Horilla needs. From inside the project directory, with the virtual environment activated, the administrator should run:

python manage.py makemigrations
python manage.py migrate

Static files should then be collected so Nginx can serve them efficiently:

python manage.py collectstatic --noinput

Next, an administrator account should be created:

python manage.py createsuperuser

The command prompts for a username, email address, and password. This account will be used to sign in to the Horilla administration interface.

Step 9: Test Horilla Locally

Before configuring a production service, the application should be tested with Django’s development server. This confirms that dependencies, database connections, and environment variables are working.

python manage.py runserver 127.0.0.1:8000

From another terminal session, the administrator can test the local response:

curl http://127.0.0.1:8000

If the page returns successfully, the installation is ready for a production service configuration. The development server should not be used as the public-facing service.

Step 10: Install and Configure Gunicorn

Gunicorn acts as the Python application server between Horilla and Nginx. It can be installed inside the virtual environment:

pip install gunicorn

The administrator should test Gunicorn manually first. The exact WSGI module name may depend on the Horilla project structure, but many Django projects use a module similar to horilla.wsgi.

gunicorn --bind 127.0.0.1:8000 horilla.wsgi:application

If the command starts without errors, it can be stopped with Ctrl+C. If an import error appears, the administrator should inspect the project directory and confirm the correct WSGI module path.

Step 11: Create a systemd Service

A systemd service allows AlmaLinux to start Horilla automatically on boot and restart it if the process fails.

sudo vim /etc/systemd/system/horilla.service

The service file can be created as follows:

[Unit]
Description=Horilla Gunicorn Service
After=network.target postgresql.service

[Service]
User=horilla
Group=horilla
WorkingDirectory=/opt/horilla/app
Environment="PATH=/opt/horilla/app/venv/bin"
ExecStart=/opt/horilla/app/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 horilla.wsgi:application
Restart=always

[Install]
WantedBy=multi-user.target

After saving the file, systemd should be reloaded and the service started:

sudo systemctl daemon-reload
sudo systemctl enable --now horilla
sudo systemctl status horilla

If the service fails, logs can be reviewed with:

journalctl -u horilla -xe

Step 12: Install and Configure Nginx

Nginx will receive browser requests and proxy them to Gunicorn. It can also serve static files and later handle TLS certificates.

sudo dnf install -y nginx
sudo systemctl enable --now nginx

A new Nginx server block can be created:

sudo vim /etc/nginx/conf.d/horilla.conf

server {
    listen 80;
    server_name example.com www.example.com;

    location /static/ {
        alias /opt/horilla/app/staticfiles/;
    }

    location /media/ {
        alias /opt/horilla/app/media/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }
}

The configuration should be tested before reloading Nginx:

sudo nginx -t
sudo systemctl reload nginx

Image not found in postmeta

Step 13: Configure Firewall and SELinux

If firewalld is enabled, HTTP and HTTPS traffic should be allowed:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

On AlmaLinux, SELinux may prevent Nginx from proxying requests to Gunicorn. The following command allows network connections from the web server:

sudo setsebool -P httpd_can_network_connect 1

File permissions should also allow Nginx to read static and media files. If static files do not load, the administrator should check ownership, directory permissions, and SELinux contexts.

Step 14: Add HTTPS with Certbot

For public deployments, HTTPS is strongly recommended. Certbot can obtain and install a free Let’s Encrypt certificate for Nginx.

sudo dnf install -y epel-release
sudo dnf install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Certbot usually configures certificate renewal automatically. The administrator can test renewal with:

sudo certbot renew --dry-run

Step 15: Final Verification

After installation, the administrator should open the domain in a browser and confirm that the Horilla login page loads. The superuser account created earlier should allow access to administrative functions. It is also useful to verify that static assets, uploaded files, and employee management modules behave correctly.

Basic operational checks include:

Confirming horilla.service is active
Checking that Nginx returns no configuration errors
Testing login with the superuser account

Confirming PostgreSQL is running after reboot
Reviewing logs for permission or database errors

Maintenance Tips

Horilla should be maintained like any other production web application. The administrator should schedule regular database backups, apply operating system updates, and keep the application code current after reviewing release notes. Before upgrading Horilla, a full backup of the database and application directory should be created.

pg_dump -U horilla_user -h 127.0.0.1 horilla_db > horilla_backup.sql

For application updates, the administrator usually pulls the latest code, updates dependencies, and re-runs migrations:

cd /opt/horilla/app
source venv/bin/activate
git pull
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --noinput
sudo systemctl restart horilla

FAQ

Can Horilla run on AlmaLinux 8?

Yes. Horilla can run on AlmaLinux 8 if the required Python version and dependencies are available. If the default Python version is too old, the administrator may need to install a newer supported Python release.

Is PostgreSQL required for Horilla?

PostgreSQL is strongly recommended for production installations. Some development setups may use SQLite, but PostgreSQL is more suitable for real HR data and multi-user environments.

Why does Nginx show a 502 Bad Gateway error?

A 502 error usually means Nginx cannot reach Gunicorn. The administrator should check whether horilla.service is running, confirm the Gunicorn bind address, and review logs with journalctl -u horilla -xe.

How can static files be fixed if they do not load?

The administrator should run python manage.py collectstatic –noinput, verify the Nginx alias path, check file permissions, and confirm SELinux is not blocking access.

Should DEBUG be enabled?

No. DEBUG=True should only be used for development or troubleshooting in a private environment. Production installations should use DEBUG=False to avoid exposing sensitive information.

How is Horilla restarted after configuration changes?

After changing environment values, code, or service settings, the administrator can restart Horilla with sudo systemctl restart horilla. If Nginx configuration changes are made, Nginx should also be tested and reloaded.