Installation

This guide walks through a complete installation of the Statalog Community edition on a Linux server. The steps assume Ubuntu 22.04 LTS, but the process is the same on Debian and similar distributions.

Server requirements

Before starting, ensure your server meets these requirements:

Component	Minimum version
PHP	8.3+ (with extensions: pdo_mysql, redis, curl, gd, xml, zip, mbstring, bcmath)
MySQL	8.0+ (or MariaDB 10.6+)
ClickHouse	23.0+
Redis	7.0+
Composer	2.x
Web server	nginx (recommended) or Apache 2.4+
Supervisor	any recent version (for queue workers)

A minimum of 2 GB RAM is recommended. ClickHouse performs best with more — 4 GB+ for sites with significant traffic.

1. Clone the repository

git clone https://github.com/statalog/analytics.git /var/www/statalog
cd /var/www/statalog

2. Install PHP dependencies

composer install --no-dev --optimize-autoloader

This installs all production dependencies and optimises the autoloader for faster class loading.

3. Configure environment

Copy the example environment file and generate an application key:

cp .env.example .env
php artisan key:generate

Open .env in your editor and fill in at minimum:

APP_URL=https://your-domain.com
APP_ENV=production
APP_DEBUG=false

DB_HOST=127.0.0.1
DB_DATABASE=statalog
DB_USERNAME=statalog
DB_PASSWORD=your-mysql-password

REDIS_HOST=127.0.0.1

STATALOG_CLICKHOUSE_HOST=127.0.0.1
STATALOG_CLICKHOUSE_PORT=8123
STATALOG_CLICKHOUSE_DB=statalog
STATALOG_CLICKHOUSE_USER=statalog
STATALOG_CLICKHOUSE_PASSWORD=your-clickhouse-password

STATALOG_API_KEY=your-long-random-api-key
STATALOG_EDITION=community

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-smtp-user
MAIL_PASSWORD=your-smtp-password
MAIL_FROM_ADDRESS=noreply@your-domain.com

See Configuration for the full list of available variables.

4. Create the MySQL database and user

mysql -u root -p <<EOF
CREATE DATABASE statalog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'statalog'@'localhost' IDENTIFIED BY 'your-mysql-password';
GRANT ALL PRIVILEGES ON statalog.* TO 'statalog'@'localhost';
FLUSH PRIVILEGES;
EOF

5. Run MySQL migrations

php artisan migrate --force

This creates all the relational tables (users, sites, goals, settings, etc.).

6. Run ClickHouse migrations

php artisan clickhouse:migrate

This creates the analytics tables in ClickHouse (pageviews, custom_events, js_errors, heatmap_clicks, heatmap_scrolls). See ClickHouse setup if you have not yet installed ClickHouse.

7. Create the admin user

php artisan statalog:create-admin

This is an interactive command that prompts for a name, email address, and password. The account it creates has full Owner access.

8. Set file permissions

chown -R www-data:www-data /var/www/statalog
chmod -R 755 /var/www/statalog/storage
chmod -R 755 /var/www/statalog/bootstrap/cache

9. Configure nginx

Create /etc/nginx/sites-available/statalog:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    root /var/www/statalog/public;
    index index.php;

    # Tracker script — long cache
    location = /st.js {
        expires 1h;
        add_header Cache-Control "public, max-age=3600";
        try_files $uri $uri/ /index.php?$query_string;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

Enable the site and reload nginx:

ln -s /etc/nginx/sites-available/statalog /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Obtain a TLS certificate with Certbot if you have not already:

certbot --nginx -d your-domain.com

10. Set up the queue worker with Supervisor

Create /etc/supervisor/conf.d/statalog-worker.conf:

[program:statalog-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/statalog/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/statalog-worker.log
stopwaitsecs=3600

Reload Supervisor:

supervisorctl reread
supervisorctl update
supervisorctl start statalog-worker:*

11. Set up the scheduler

Add a cron entry for the Laravel scheduler, which handles email digests, traffic alerts, and data aggregation:

crontab -e -u www-data

Add:

* * * * * php /var/www/statalog/artisan schedule:run >> /dev/null 2>&1

12. Optimise for production

php artisan config:cache
php artisan route:cache
php artisan view:cache

First login

Visit https://your-domain.com in your browser, log in with the admin credentials you created in step 7, click Add Site, and install the tracking snippet on your website. Data will begin appearing within seconds of your first tracked pageview.