Install Horilla on AlmaLinux: Complete Installation and Configuration Tutorial

Installing Horilla on AlmaLinux sounds serious. But do not worry. We will treat it like building a sandwich. One layer is Python. One layer is PostgreSQL. One layer is Nginx. At the end, you get a tasty HR management app running on your server.

TLDR: Install system packages, PostgreSQL, Python tools, and Nginx. Clone Horilla, create a virtual environment, install dependencies, and configure the database. Then run migrations, create an admin user, and serve Horilla with Gunicorn and Nginx. Add SSL when everything works.

What Is Horilla?

Horilla is an open source HRMS platform. It helps manage employees, attendance, leave, recruitment, payroll, and more. It is built with Django, which means Python does most of the heavy lifting.

In this guide, we will install Horilla on AlmaLinux 9. The same steps should also work on many RHEL based systems with small changes.

Before You Start

You need a few things first:

• A fresh AlmaLinux server.
• A user with sudo access.
• A domain name, if you want public access.
• Basic comfort with the terminal.

If your server is new, update it first. Fresh packages make happy servers.

sudo dnf update -y
sudo reboot

After the reboot, log back in.

Step 1: Install Required Packages

Horilla needs Python, Git, PostgreSQL, compiler tools, and Nginx. Install them with one command:

sudo dnf install -y git python3 python3-pip python3-devel gcc gcc-c++ make \
postgresql-server postgresql-contrib postgresql-devel nginx \
policycoreutils-python-utils

Now start and enable Nginx. We will configure it later.

sudo systemctl enable --now nginx

Also open the firewall for web traffic:

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

Step 2: Set Up PostgreSQL

Horilla needs a database. PostgreSQL is a strong choice. It is fast, reliable, and not dramatic.

Initialize the database:

sudo postgresql-setup --initdb

Start PostgreSQL:

sudo systemctl enable --now postgresql

Now create a database and user for Horilla:

sudo -iu postgres psql

Inside the PostgreSQL shell, run:

CREATE DATABASE horilla;
CREATE USER horillauser WITH PASSWORD 'ChangeThisStrongPassword';
ALTER ROLE horillauser SET client_encoding TO 'utf8';
ALTER ROLE horillauser SET default_transaction_isolation TO 'read committed';
ALTER ROLE horillauser SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE horilla TO horillauser;
\c horilla
GRANT ALL ON SCHEMA public TO horillauser;
\q

Important: Replace ChangeThisStrongPassword with a real strong password. Not your dog’s name. Not “password123”. The internet has no chill.

Step 3: Download Horilla

We will place Horilla in /opt/horilla. This keeps things tidy.

sudo mkdir -p /opt/horilla
sudo chown $USER:$USER /opt/horilla
git clone https://github.com/horilla-opensource/horilla.git /opt/horilla
cd /opt/horilla

Now create a Python virtual environment. This keeps Horilla’s Python packages away from the system packages.

python3 -m venv venv
source venv/bin/activate

Upgrade pip and install the project requirements:

pip install --upgrade pip wheel
pip install -r requirements.txt
pip install gunicorn psycopg2-binary

Step 4: Configure Environment Settings

Many Django projects use an environment file. If Horilla includes an example file, copy it first:

cp .env.example .env 2>/dev/null || touch .env

Open the file:

nano .env

Add or update these values. If your Horilla version uses slightly different names, match the names from its sample file.

DEBUG=False
SECRET_KEY=replace_this_with_a_long_random_secret
ALLOWED_HOSTS=yourdomain.com,server_ip_address,localhost
DB_ENGINE=django.db.backends.postgresql
DB_NAME=horilla
DB_USER=horillauser
DB_PASSWORD=ChangeThisStrongPassword
DB_HOST=127.0.0.1
DB_PORT=5432

You can generate a quick secret key with:

python -c "import secrets; print(secrets.token_urlsafe(50))"

Save the file. Your app now knows where the database lives. Nice.

Step 5: Run Django Setup Commands

Now we prepare the database tables. Think of this as setting up the furniture before the guests arrive.

cd /opt/horilla
source venv/bin/activate
python manage.py makemigrations
python manage.py migrate

Collect static files:

python manage.py collectstatic --noinput

Create the admin user:

python manage.py createsuperuser

Test Horilla before making it fancy:

python manage.py runserver 0.0.0.0:8000

Visit:

http://your_server_ip:8000

If you see Horilla, celebrate. Small dance allowed.

Step 6: Create a System User

Running apps as your personal user is not ideal. Create a dedicated user:

sudo useradd --system --home /opt/horilla --shell /sbin/nologin horilla
sudo chown -R horilla:horilla /opt/horilla

Step 7: Configure Gunicorn

Gunicorn will run Horilla in the background. Create a systemd service:

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

Add this:

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

[Service]
User=horilla
Group=horilla
WorkingDirectory=/opt/horilla
EnvironmentFile=/opt/horilla/.env
ExecStart=/opt/horilla/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8001 horilla.wsgi:application
Restart=always

[Install]
WantedBy=multi-user.target

Start it:

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

If it says active, you are winning.

Step 8: Configure Nginx

Now we place Nginx in front of Gunicorn. Nginx handles browser traffic. Gunicorn handles Python. Teamwork!

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

Add this configuration:

server {
    listen 80;
    server_name yourdomain.com;

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

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

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

Test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Allow Nginx to connect to the local Gunicorn service under SELinux:

sudo setsebool -P httpd_can_network_connect 1

Step 9: Add HTTPS

For production, use HTTPS. Install Certbot:

sudo dnf install -y certbot python3-certbot-nginx

Request a certificate:

sudo certbot --nginx -d yourdomain.com

Follow the prompts. Certbot will edit Nginx for you. It also sets up renewal. Very polite software.

Step 10: Useful Maintenance Commands

Here are your daily helper spells:

• Restart Horilla: sudo systemctl restart horilla
• View logs: sudo journalctl -u horilla -f
• Reload Nginx: sudo systemctl reload nginx
• Run migrations after updates: python manage.py migrate
• Collect static files: python manage.py collectstatic --noinput

Final Notes

You now have Horilla installed on AlmaLinux with PostgreSQL, Gunicorn, and Nginx. That is a proper production style setup. Keep your server updated. Back up your database. Use strong passwords. And please, do not ignore logs. Logs are like tiny server diaries. They know things.

From here, log in to Horilla and start configuring departments, employees, attendance, leave policies, and roles. Your HR platform is ready to work. Coffee is optional, but recommended.