Installation

The same package installs in a domain root, on a sub-domain or in a sub-folder. No file needs editing before you start.

1. Upload

Upload the contents of the upload/ folder (not the folder itself) to the place the site should live:

Where	Example	Upload to
Domain root	`https://billing.example.com`	the document root of that domain
Sub-folder	`https://example.com/billing`	`public_html/billing/`
Sub-domain	`https://my.example.com`	the document root of the sub-domain

Keep the hidden files: .htaccess in the package root, in public/, in public/uploads/ and in public/extensions/. Some FTP clients hide them by default. The root .htaccess sends visitors into public/ and blocks access to everything else, so the application's private files are never reachable even though they sit next to the public folder.

If your host lets you choose the document root, pointing it at the public/ folder is also fine. Both layouts are supported without changing public/index.php.

2. Permissions

The web server must be able to write to storage/ (with all sub-folders), bootstrap/cache/, public/uploads/, public/extensions/ and extensions/. On most shared hosts the uploaded files already belong to the right user and nothing has to change. The installer's requirements page shows which folders are not writable.

3. The web installer

Open the site in a browser. The setup wizard runs through these steps:

Requirements. PHP version, extensions, PHP limits and folder permissions. You cannot continue while a required check fails.
Setup code. When the package is first opened it writes a one-time code to storage/app/setup-code.txt. Open that file with your file manager or FTP client and enter the code. This proves that whoever installs the application also controls the server, so nobody else can finish the installation for you. The file is deleted when the installation completes.
Database. MySQL or MariaDB (host, port, name, user, password and an optional table prefix) or SQLite. The connection is tested before you continue, and a database that already holds TWERPLEX tables is refused.
Licence. The purchase code or licence key for this copy and the domain it is installed on. See Licence.
Owner account. Company name, site address, time zone and the owner's name, email address and password. Passwords are stored as hashes only.
Done. The cron job line, a check that private files such as .env are really blocked on your server, and a link to the staff area. This page is shown once, so copy the cron line before you leave.

Do not run php artisan key:generate before installing. The installer creates the configuration file and the encryption key itself. An existing .env makes the installer refuse to run.

Installing from the command line

With shell access you can install without opening the wizard at all, so nothing is reachable from the web before the owner account exists:

cd /path/to/twerplex
php artisan twerplex:install

The command asks for everything the wizard asks for. Values can also be passed as options (--url, --db-connection, --db-host, --db-port, --db-database, --db-username, --db-password, --db-prefix, --admin-name, --admin-email, --admin-password, --company, --timezone, --license); passwords left out are asked for without echo. After the command finishes, add the cron job and open /admin.

nginx

nginx does not read .htaccess files. Point the server block at the public/ folder and deny scripts in the upload folders:

server {
    listen 443 ssl http2;
    server_name billing.example.com;
    root /var/www/twerplex/public;
    index index.php;

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

    # No scripts from user uploads or published extension assets.
    location ~* ^/(uploads|extensions)/.*\.(php|phtml|phar)$ {
        deny all;
    }

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

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

If nginx is pointed at the package root instead of public/, the application shows a page titled "Your web server needs one more step" with these rules rather than serving anything.

Sub-folder notes

Links, cookies and the trusted host come from the site address you entered, so a sub-folder installation needs no extra configuration.
Moving the installation later means changing APP_URL in .env; see Troubleshooting.

After installing

Add the cron job. Invoices, renewals, emails, provisioning and backups depend on it.
Set up email and send a test message.
The first database backup is queued during installation and runs as soon as the cron does.
The installer is closed for good once the installation completes; opening /install again shows a 404.