Skip to main content

Installing JasperWho?

JasperWho? is a standard Laravel application. The setup is intentionally slim — pull the repository, install dependencies, configure the environment, migrate the database. A standard installation is up and running in under 30 minutes.

What You Don't Need

Before listing what is required, it is worth being explicit about what is not:

    No Java — the render engine is pure PHP. No JVM, no Java runtime, no Java SQL drivers. No Node.js / npm / Vite — the frontend assets are pre-built and bundled with the repository. No Jaspersoft Server — JasperWho? is entirely self-contained. No Docker — optional for the database only, not required for the application itself.

    System Requirements

    Requirement Notes PHP >= 8.2 With common extensions: pdo, pdo_mysql, mbstring, xml, simplexml, gd, zip, curl, bcmath, fileinfo, openssl Composer PHP dependency manager — getcomposer.org MySQL or MariaDB JasperWho?'s own application database. A Docker container works fine if no local instance is available. poppler-utils Provides pdftoppm, used for generating report thumbnails. Install via apt install poppler-utils. Supervisor Keeps the Laravel queue worker running for background jobs (thumbnail generation, purge tasks). Apache2 or nginx Optional reverse proxy. Not required for local or development setups. php-sqlsrv / pdo_sqlsrv Only required when connecting to Microsoft SQL Server as a report data source. Not needed otherwise.

    Bundled Dependencies

    The following components are bundled with JasperWho? — no separate installation required:

    Component Purpose JasperPHP Pure PHP render engine — parses .jrxml and generates PDFs via TCPDF. Installed automatically by Composer. Google Material Design Icons Icon set used throughout the frontend. Ace Editor In-browser code editor for writing SQL queries. Jaspersoft Studio 6.21.5 Desktop IDE for designing .jrxml report templates. Installed separately on the designer's machine — not on the server. Download here.

    Installation

    1. Pull the Repository

    git clone <repository-url> jasperwho
cd jasperwho

    2. Install PHP Dependencies

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

    3. Set Up the Database

    Create a MySQL or MariaDB database for JasperWho?. If no local database server is available, a Docker container is the quickest path:

    docker run -d \
  --name jasperwho-db \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=jasperwho \
  -p 3306:3306 \
  mysql:8

    4. Configure the Environment

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

    Open .env and configure at minimum the database connection and application URL:

    APP_URL=http://your-domain-or-ip

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=jasperwho
DB_USERNAME=your_user
DB_PASSWORD=your_password

    All other JasperWho?-specific settings (rate limits, history retention, etc.) are documented on the Configuration and Data Models page.

    5. Run Migrations

    php artisan migrate --force

    This creates all required database tables. Afterwards, run the seeder to create the admin account and base configuration:

    php artisan db:seed

    6. Set File Permissions

    chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

    7. Install poppler-utils

    apt install poppler-utils

    Required for thumbnail generation. Verify the installation with pdftoppm -v.

    Supervisor — Background Jobs

    JasperWho? uses Laravel's queue system for background tasks: generating thumbnails after rendering, purging old history records and print tasks, and cleaning up orphaned files. Supervisor keeps the queue worker alive.

    Create a Supervisor configuration file, e.g. /etc/supervisor/conf.d/jasperwho-worker.conf:

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

    Then reload Supervisor:

    supervisorctl reread
supervisorctl update
supervisorctl start jasperwho-worker:*

    Web Server (Optional Reverse Proxy)

    For production use, running JasperWho? behind a reverse proxy is recommended. Both Apache2 and nginx work well.

    nginx

    server {
    listen 80;
    server_name your-domain.com;
    root /var/www/jasperwho/public;

    index index.php;

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

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

    Apache2

    <VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/jasperwho/public

    <Directory /var/www/jasperwho/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

    Ensure mod_rewrite is enabled: a2enmod rewrite.

    ℹ️ For HTTPS, use Certbot to obtain a free Let's Encrypt certificate. Set APP_SCHEME=https in .env afterwards so generated file URLs use the correct scheme.

    Managed Hosting

    If you prefer not to manage infrastructure yourself, JasperWho? can be hosted and operated for you. Instances run exclusively in Germany on Hetzner hardware — reliable, fast, and GDPR-compliant by location.

    Cloud-hosted JasperWho? works well for most use cases. Depending on your network connection to the hosting location, render requests may see slightly higher latency compared to a locally deployed instance — typically not noticeable, but worth considering for high-frequency, latency-sensitive workloads like real-time label printing on the shop floor.

    For managed hosting enquiries, get in touch directly.

    Back to top