Installation

Before you start

Check that your server meets the Requirements.

You need:

• PHP 8.4 or newer
• SQLite, MySQL, or MariaDB
• Required PHP extensions
• Writable storage/ and bootstrap/cache/

Upload files

Extract the InvoiceScript release zip and upload the full application to your hosting account.

The release zip includes vendor/ and public/build/. Do not run composer install, npm install, or npm run build for a normal buyer installation.

For Apache hosting, make sure the included .htaccess files are uploaded. The root .htaccess lets shared hosting accounts serve InvoiceScript even when the host cannot point the document root directly at public/. For Nginx hosting, configure your site to route requests to public/index.php.

InvoiceScript runtime assets are local. The admin UI, PDFs, charts, icons, and fonts do not depend on CDNs.

Run the web installer

Visit your domain in a browser. You will be redirected to the web installer, which guides you through three steps:

1. Requirements -- the installer checks PHP version, required extensions, writable directories, mod_rewrite, cURL HTTPS support, and SQLite JSON support. Hard requirements must pass before you can proceed. Checks marked as optional (such as SQLite JSON when MySQL is also available) show a warning but do not block installation.
2. Configure -- enter your business name, set the database connection (SQLite or MySQL/MariaDB), create the owner account, select the timezone, and configure email delivery (SMTP, Resend API, Mailpit, or log mode).
3. Install -- review your configuration summary. Optionally enable "Add demo data" to create demo user accounts for evaluation (leave off for production). Confirm to run database migrations, create the owner account, and mark the application as installed.

After installation completes, you are redirected to the sign-in page where you can log in with the owner credentials you created.

Database options

The installer detects which database drivers are available on your server:

• If only SQLite is available, it is preselected and no further database configuration is needed.
• If only MySQL/MariaDB is available, you will be prompted for the host, port, database name, and credentials.
• If both are available, you can choose either option.

InvoiceScript requires an empty database for a fresh installation. If the target database already contains tables, the installer displays an error and offers two options:

• Reset from the installer -- click "Reset database" and type RESET DATABASE to confirm. The installer empties the database so you can proceed. For SQLite this deletes and recreates the database file. For MySQL/MariaDB this drops all tables.
• Clear the database yourself -- back up the database, remove all tables through your hosting panel or database tool, and retry the installation. You can also create a new empty database and update the connection details.

Email configuration

The installer offers four email modes:

• SMTP -- enter your SMTP server host, port, username, password, and encryption method. Works with any SMTP provider (Gmail, Outlook, Amazon SES, Mailgun, etc.).
• Resend -- enter your Resend API key from resend.com. No SMTP server details needed. Resend delivers email through its API.
• Mailpit -- uses a local Mailpit instance on 127.0.0.1:1025. Ideal for development with Laravel Herd or Docker.
• Log mode -- emails are written to the application log file instead of being sent. This is useful for testing or when email delivery is not yet configured. You can switch to SMTP or Resend later by editing the .env file.

Installation logging

After a successful installation, InvoiceScript writes a log entry to storage/logs/laravel.log recording the database driver, email mode, and a hashed owner email identifier. No passwords, API keys, SMTP credentials, or raw email addresses are included in the log entry.

A system.installed audit log entry is also written to the audit_logs database table. This is the first entry in the structured audit trail that InvoiceScript maintains for security and compliance events.

Failure recovery

If installation fails during database migrations or owner account creation, the .env file is not written. The application remains in an uninstalled state, and the installer is accessible again on the next visit. Fix the underlying issue (database connection, permissions, etc.) and retry the installation.

If a previous attempt left tables in the database, use the installer's built-in "Reset database" button to clear them before retrying. See Database options above for details.

Data recovery

If you need to restore InvoiceScript after a server failure or hosting migration:

1. Upload the release ZIP to the new server
2. Run the web installer to configure a fresh database and owner account
3. Restore your data from a backup using Settings > Backups or the backup:create / restore workflow

You need both the application code (from the release ZIP) and a data backup to fully restore. The .env file is not included in backups — you will need to reconfigure database and email settings.

See Backups for full backup and restore procedures.

Troubleshooting

See Common Issues for blank pages, permission errors, missing extensions, database problems, and email delivery issues.