Skip to content
Suricatavel Logo Suricatavel Logo Suricatavel

Installation

This guide covers the manual installation of Suricatavel with full control over each component.

For a quick automated installation, see the Quickstart Guide.

Installation steps

Section titled “Installation steps”

Step 1: Install PostgreSQL 18 and TimescaleDB

Section titled “Step 1: Install PostgreSQL 18 and TimescaleDB”

  1. Add repositories

    Terminal window
    # Add PostgreSQL repository
     apt-get install -y gnupg2 wget lsb-release
     mkdir -p /usr/share/keyrings
    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor -o /usr/share/keyrings/postgresql-archive-keyring.gpg
    echo "deb [signed-by=/usr/share/keyrings/postgresql-archive-keyring.gpg] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | tee /etc/apt/sources.list.d/pgdg.list
    

    # Add TimescaleDB repository
    wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | gpg --dearmor -o /usr/share/keyrings/timescaledb-archive-keyring.gpg
    echo "deb [signed-by=/usr/share/keyrings/timescaledb-archive-keyring.gpg] https://packagecloud.io/timescale/timescaledb/ubuntu/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/timescaledb.list

  2. Install packages

    Terminal window
     apt-get update
     apt-get install -y postgresql-18 postgresql-client-18 timescaledb-2-postgresql-18
    

    # Ensure PostgreSQL 18 cluster exists (optional if already created by install)
    # If the cluster 'main' already exists, this command will safely error out or can be skipped
    if ! pg_lsclusters | grep -q "18 main"; then
         pg_createcluster 18 main --start
    fi
    

    # Optimize PostgreSQL configuration
    # --quiet --yes runs it non-interactively with recommended settings
     timescaledb-tune --quiet --yes
    

     systemctl restart postgresql

  3. Create Database

    Terminal window
    # Create database and user
     sudo -u postgres psql -c "CREATE USER suricatavel WITH PASSWORD 'secret_password';"
     sudo -u postgres psql -c "CREATE DATABASE suricataveldb OWNER suricatavel;"

Step 2: Install PHP (8.4 or 8.5)

Section titled “Step 2: Install PHP (8.4 or 8.5)”
Terminal window
# Add Ondřej Surý PHP PPA
 apt install -y lsb-release ca-certificates apt-transport-https software-properties-common
 add-apt-repository ppa:ondrej/php -y
 apt update


# Install PHP 8.4 and extensions
 apt install -y php8.4-cli \
    php8.4-pgsql php8.4-pdo \
    php8.4-mbstring php8.4-xml php8.4-curl \
    php8.4-zip php8.4-bcmath php8.4-intl \
    php8.4-redis php8.4-opcache


# Optional: Kafka extension (only if using Kafka transport)
 apt install -y php8.4-rdkafka

Verify PHP installation:

Terminal window
php -v
php -m | grep -E "pdo|pgsql|pcntl|posix"

Step 3: Install Nginx

Section titled “Step 3: Install Nginx”
Terminal window
 apt install -y nginx

Configure Nginx for Suricatavel:

Create /etc/nginx/sites-available/suricatavel (or conf.d/suricatavel.conf on RHEL):

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;
    root /var/opt/suricatavel/public;


    index index.php;
    error_page 404 /index.php;


    # Main application handling through Octane (Swoole)
    location / {
        proxy_pass http://127.0.0.1:8089;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header Scheme $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }


    # Reverb WebSocket server
    location /apps/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }


    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable the site:

Terminal window
 ln -s /etc/nginx/sites-available/suricatavel /etc/nginx/sites-enabled/
 nginx -t
 systemctl restart nginx

Step 4: Install Supervisor

Section titled “Step 4: Install Supervisor”
Terminal window
 apt install -y supervisor
 systemctl enable --now supervisor

Step 5: Configure Suricatavel repository

Section titled “Step 5: Configure Suricatavel repository”
Terminal window
# Import GPG key
curl -fsSL https://suricatavel.org/suricatavel.gpg | gpg --dearmor -o /etc/apt/keyrings/suricatavel.gpg


# Add repository
echo "deb [signed-by=/etc/apt/keyrings/suricatavel.gpg] https://repository.suricatavel.org stable main" | tee /etc/apt/sources.list.d/suricatavel.list > /dev/null


# Update package cache
 apt update

Step 6: Install Suricatavel package

Section titled “Step 6: Install Suricatavel package”
Terminal window
 apt install -y suricatavel

What the package does:

  1. Creates system user suricatavel (no login shell).
  2. Installs application files to /var/opt/suricatavel.
  3. Creates working directories with proper permissions.
  4. Generates APP_KEY for Laravel.
  5. Runs database migrations (if DB is accessible).
  6. Configures Supervisor workers.
  7. Builds Laravel caches.

Step 7: Configure the application

Section titled “Step 7: Configure the application”

Edit the environment file:

Terminal window
 nano /var/opt/suricatavel/.env

Essential configuration:

Terminal window
APP_NAME=Suricatavel
APP_ENV=production
APP_DEBUG=false
APP_URL=http://your-domain.com


DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=suricataveldb
DB_USERNAME=suricatavel
DB_PASSWORD=secret_password


# Optional: Kafka Configuration (High throughput)
#KAFKA_BROKERS=localhost:9092
#KAFKA_CONSUMER_GROUP_ID=suricatavel


# Optional: HTTP Configuration (Simpler setup)
#SURICATAVEL_AGENT_TRANSPORT=http
#SURICATAVEL_AGENT_HTTP_ENDPOINT=http://your-domain.com/api/v1/events
#SURICATAVEL_AGENT_HTTP_TOKEN=your-agent-token


# Optional: Redis for cache
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379


# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls

If the database was not accessible during installation, run migrations manually:

Terminal window
 suricatavel deploy --migrate

Rebuild caches after configuration changes:

Terminal window
suricatavel maintenance cache

Step 8: Verify workers

Section titled “Step 8: Verify workers”

The suricatavel package automatically configures Supervisor. Check the status:

Terminal window
suricatavel status

You should see processes like web, worker, scheduler in RUNNING state. If Kafka is enabled, kafka should also be running.

Post-installation

Section titled “Post-installation”

Initialize Suricatavel

Section titled “Initialize Suricatavel”

Initialize the application:

Terminal window
suricatavel boot

Or in non-interactive mode (creates default admin user):

Terminal window
suricatavel boot -s

Default credentials:

Update Suricatavel

Section titled “Update Suricatavel”

For zero-downtime updates with automatic rollback, use the CLI:

Terminal window
suricatavel update

The update command will handle backup, maintenance mode, package updates, and migrations automatically.

For manual updates via package manager:

Terminal window
apt update
apt upgrade suricatavel

Troubleshooting

Section titled “Troubleshooting”

See the Quickstart Guide for common issues.

Next steps

Section titled “Next steps”

For questions or issues, consult the FAQ or contribute.