Manual Installation

Use manual installation when you already manage the web stack, need separate FlinkISO and ONLYOFFICE hosts, or cannot use the single-server installer. This chapter keeps the complete configuration reference for the Free On-Premise edition.

Server and software prerequisites

FlinkISO runs on a Linux/Apache/MySQL/PHP stack and can also be configured on a Windows server with Apache or IIS. Prepare the following before copying the application:

• Linux or Windows server
• Apache or IIS with URL rewriting enabled
• MySQL
• A supported PHP-FPM version with cURL, mbstring, MySQL, XML, Intl, GD and ZIP extensions
• pdftk-java and a headless Java runtime for PDF merging, passwords and permissions
• ONLYOFFICE Community Document Server
• A static IP address or qualified domain for a separate ONLYOFFICE host
• HTTPS for production use

If you need a packaged local Apache environment, MAMP or XAMPP can be used for testing. Production deployments should use a properly secured and maintained web-server configuration.

Install PDF tools on Ubuntu

sudo apt install pdftk-java default-jre-headless
sudo -u www-data /usr/bin/pdftk.pdftk-java --version

Register and copy the application

1. Register for the download. Use the Free On-Premise download page and retain the access details sent to your registered email address.
2. Download the supplied package. Keep its included application libraries and schema unchanged.
3. Copy FlinkISO to the web root. Use /var/www/html/flinkiso, your virtual host’s document directory, or the site directory configured in Apache or IIS.
4. Install ONLYOFFICE. Note its browser API URL, conversion API URL and JWT secret before editing FlinkISO configuration.

Configure ONLYOFFICE

Open /etc/onlyoffice/documentserver/local.json. Keep JWT enabled and use one consistent secret for browser, inbox, outbox and session. Put the same secret in FlinkISO’s app/Config/core.php.

When the Document Server must access FlinkISO on a private network, add the request-filtering agent inside services.CoAuthoring, before the sql section:

"request-filtering-agent": {
  "allowPrivateIPAddress": true,
  "allowMetaIPAddress": true
}

Restart ONLYOFFICE services after changing local.json. A mismatch between the ONLYOFFICE and FlinkISO secrets causes the “document security token is not correctly formed” error.

Update Core.php and Database.php

Application configuration

Open your_directory/flinkiso/app/Config/core.php and review each environment-specific value:

• Do not change ApiPath.
• Set OnlyofficePath to the ONLYOFFICE browser API location.
• Set onlyofficesecret to the secret copied from local.json.
• Set OnlyofficeConversionApi to the Document Server conversion API.
• Set PDFTkPath to /usr/bin/pdftk.pdftk-java on supported Ubuntu releases.
• Replace the timezone in date_default_timezone_set(...) with the server’s required timezone.
• Replace Security.salt with a unique value of the same length before registering the instance.
• Replace Security.cipherSeed with a unique numeric value of the same length before registering the instance.
• Set dateFormat to the format required in exported PDFs.

Configure::write('PDFTkPath', '/usr/bin/pdftk.pdftk-java');

Database configuration

Open your_directory/flinkiso/app/Config/database.php and enter the MySQL connection details:

public $default = array(
    "datasource" => "Database/Mysql",
    "persistent" => false,
    "host"       => "localhost",
    "login"      => "your_database_user",
    "password"   => "your_database_password",
    "database"   => "flinkiso",
    "prefix"     => "",
    "encoding"   => "utf8",
);

Create and import the database

1. Create an empty MySQL database named flinkiso, or use the database name entered in database.php.
2. Create a dedicated database user and grant it the required privileges on that database.
3. Locate app/webroot/schema/flinkiso-on-premise.sql in the downloaded package.
4. Import the SQL file with phpMyAdmin or the MySQL command-line client.
5. Open the application URL and check the CakePHP logs if a database connection or missing-table error appears.

Example command-line import:

mysql -u your_database_user -p flinkiso < app/webroot/schema/flinkiso-on-premise.sql

Configure outgoing email

Open your_directory/flinkiso/app/Config/Email.php. Configure the $default, $smtp and $fast profiles with your organisation’s sender and SMTP credentials. These profiles support password resets, approval messages, notifications and other application email.

class EmailConfig {
    public $default = array(
        "transport" => "Mail",
        "from" => array("[email protected]" => "FlinkISO")
    );

    public $smtp = array(
        "transport" => "Smtp",
        "from" => array("[email protected]" => "FlinkISO"),
        "host" => "your_smtp_host",
        "port" => 465,
        "timeout" => 30,
        "username" => "your_smtp_username",
        "password" => "your_smtp_password",
        "client" => null,
        "log" => false
    );

    public $fast = array(
        "from" => "[email protected]",
        "sender" => null,
        "to" => null,
        "cc" => null,
        "bcc" => null,
        "replyTo" => null,
        "readReceipt" => null,
        "returnPath" => null,
        "messageId" => true,
        "subject" => null,
        "message" => null,
        "headers" => null,
        "viewRender" => null,
        "template" => false,
        "layout" => false,
        "viewVars" => null,
        "attachments" => null,
        "emailFormat" => null,
        "transport" => "Smtp",
        "host" => "your_smtp_host",
        "port" => 465,
        "timeout" => 30,
        "username" => "your_smtp_username",
        "password" => "your_smtp_password",
        "client" => null,
        "log" => true
    );
}

Set directory permissions

The web-server account must be able to write to the application’s runtime, generated-code and uploaded-file locations. The published package identifies these paths:

Set ownership to the web-server user and grant only the permissions required by your deployment. Avoid unrestricted world-writable permissions on a production server.

Apache, MySQL and PHP settings

Install PHP-FPM and enable the required Apache modules

Use PHP 8.2 on Ubuntu 22.04/24.04 or PHP 8.5 on Ubuntu 26.04. Set the version once before running the remaining commands:

# Ubuntu 22.04 or 24.04
FLINKISO_PHP_VERSION=8.2

# Ubuntu 26.04
# FLINKISO_PHP_VERSION=8.5

sudo apt install "php${FLINKISO_PHP_VERSION}-fpm" "php${FLINKISO_PHP_VERSION}-cli" \
  "php${FLINKISO_PHP_VERSION}-curl" "php${FLINKISO_PHP_VERSION}-mbstring" \
  "php${FLINKISO_PHP_VERSION}-mysql" "php${FLINKISO_PHP_VERSION}-xml" \
  "php${FLINKISO_PHP_VERSION}-intl" "php${FLINKISO_PHP_VERSION}-gd" \
  "php${FLINKISO_PHP_VERSION}-zip"

sudo a2dismod "php${FLINKISO_PHP_VERSION}" 2>/dev/null || true
sudo a2dismod mpm_prefork 2>/dev/null || true
sudo a2enmod mpm_event proxy proxy_fcgi setenvif rewrite headers
sudo a2enconf "php${FLINKISO_PHP_VERSION}-fpm"
sudo systemctl enable --now "php${FLINKISO_PHP_VERSION}-fpm"
sudo systemctl restart apache2

Allow application rewrite rules

In /etc/apache2/apache2.conf, httpd.conf or the site’s virtual-host configuration, allow overrides for the FlinkISO web root. For Apache 2.4 and later:

<Directory /var/www/>
    Options FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

If phpMyAdmin also requires overrides, add the appropriate directory rule for /usr/share/phpmyadmin:

<Directory /usr/share/phpmyadmin>
    Options SymLinksIfOwnerMatch
    DirectoryIndex index.php
    AllowOverride All
</Directory>

Verify PHP-FPM and pdftk-java

sudo systemctl status "php${FLINKISO_PHP_VERSION}-fpm"
sudo systemctl show "php${FLINKISO_PHP_VERSION}-fpm" -p MemoryDenyWriteExecute
sudo apache2ctl -M | grep -E 'mpm_event|proxy_fcgi'
sudo -u www-data /usr/bin/pdftk.pdftk-java --version

Review MySQL SQL mode

If the supplied schema or application behavior requires the compatibility mode used by the published installation guide, review /etc/mysql/mysql.conf.d/mysqld.cnf and set:

sql_mode = "STRICT_TRANS_TABLES, NO_ZERO_IN_DATE, NO_ZERO_DATE,
ERROR_FOR_DIVISION_BY_ZERO, NO_AUTO_CREATE_USER, NO_ENGINE_SUBSTITUTION"

Available SQL modes vary between MySQL releases. Remove a mode only when the server reports that it is unsupported, then restart MySQL and retest the application.

Review PHP limits

Open /etc/php/<your-php-version>/fpm/php.ini and set limits suitable for controlled documents and generated forms:

max_execution_time = 300
max_input_time = 600
post_max_size = 80M
upload_max_filesize = 200M
pcre.jit = 0

Adjust these values to your organisation’s restrictions, then restart PHP-FPM and Apache.

sudo systemctl restart "php${FLINKISO_PHP_VERSION}-fpm" apache2

Register and verify the instance

1. Open https://your-server/flinkiso/users/register, adjusted for your actual host and application directory.
2. Enter the same registered email address used to obtain the download and proceed with instance registration.
3. Sign in with the credentials supplied for the registered installation and change any temporary password immediately.
4. Add a location, department and employee record to verify database writes.
5. Open an office document to verify the ONLYOFFICE URL and JWT secret.
6. Generate individual, selected and combined password-protected PDFs to verify ONLYOFFICE conversion and pdftk-java security.
7. Send a password reset or test approval notification to verify SMTP.
8. Build or rebuild a test form and confirm generated code, cache and webroot permissions.