Skip to main content

Distribution package

The distribution package is a pre-built archive of SolidInvoice that you serve from an existing PHP webserver. Choose this method when you can't use the quick install — for example on shared hosting, on a managed PHP host, or when company policy requires you to use a specific webserver.

warning

This is the most involved install method. You're responsible for the webserver, PHP, the database, the cron job, and the async worker. If you have a choice, the quick install, Homebrew, or Docker installs handle all of this for you.

Skip the setup entirely

The hosted version of SolidInvoice takes care of the webserver, updates, and backups. It has a Free plan, and paid plans start at $9/month (see pricing).

System requirements​

  • PHP 8.4 or higher with the following extensions enabled: curl, gd, intl, json, openssl, pdo, soap, xsl. You'll also need a pdo driver for your database (pdo_mysql, pdo_pgsql, or pdo_sqlite).
  • A webserver — Nginx (recommended) or Apache with mod_rewrite.
  • A supported database (MySQL, MariaDB, PostgreSQL, or SQLite).
  • The ability to run a cron job and a long-running PHP process on the host.

1. Download​

Download the latest archive from the SolidWorx download server:

# Zip
curl -LO https://download.solidworx.co/solidinvoice/latest/archive/zip

# Or tar.gz
curl -LO https://download.solidworx.co/solidinvoice/latest/archive/tar.gz

Extract it to a directory served by your webserver, for example /opt/solidinvoice.

info

On shared hosting with FTP-only access, download the archive locally, extract it, and upload the extracted files to your hosting account.

2. Configure the webserver​

Point your webserver at the public/ directory inside the extracted archive.

server {
    server_name yourdomain.com www.yourdomain.com;
    root /opt/solidinvoice/public;

    location / {
        # try to serve file directly, fallback to index.php
        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTPS off;
    }

    error_log /var/log/nginx/solidinvoice_error.log;
    access_log /var/log/nginx/solidinvoice_access.log;
}
warning

The exact paths (PHP-FPM socket, log directories) differ by operating system and PHP version. Adjust to match your environment.

Open your browser at the URL the webserver is serving and finish setup with the first-run wizard — it walks you through the database connection, the admin user, and the basic application settings.

3. Run the background worker​

SolidInvoice uses a single background worker for both async messages (emails, webhook dispatch) and scheduled tasks (recurring invoices, reminders, overdue checks). The worker runs bin/console messenger:consume --all in a loop.

Follow the cron job setup guide — it covers systemd, cron, cPanel, Plesk, and Windows Task Scheduler.

warning

Without the worker running, async features and scheduled tasks won't fire — emails won't send and recurring invoices won't generate.

Useful environment variables​

The first-run wizard configures everything you need to get started. The variables below are useful when you want to override settings, automate deployment, or configure things the wizard doesn't ask about. Set them in .env.local (or your webserver's environment).

VariableDescription
SOLIDINVOICE_ENVApplication environment. Use prod in production.
SOLIDINVOICE_DEBUGEnable verbose error pages. Set to 0 in production.
SOLIDINVOICE_APP_SECRETLong random string used to sign cookies and CSRF tokens.
SOLIDINVOICE_APPLICATION_URLPublic URL of the installation, e.g. https://invoice.example.com.
SOLIDINVOICE_DATABASE_URLDatabase DSN. The first-run wizard can also write this for you.
SOLIDINVOICE_MAILER_DSNOutbound mail transport (SMTP, Mailgun, SendGrid, etc.). Overrides the transport configured in the UI.
SOLIDINVOICE_MAILER_SENDERThe From: address SolidInvoice sends mail from. Overrides the address configured in the UI.
SOLIDINVOICE_LOCALEDefault locale (e.g. en).
SOLIDINVOICE_LOCK_DSNWhere locks are stored (used to stop a retried API request being applied twice). Defaults to flock, which only works on one server. When several servers share the installation, point it at a shared store, e.g. redis://redis:6379. The stored responses and the API rate limits are kept in the application cache, which is per server, so a retry that reaches a different server is not recognised.
SOLIDINVOICE_AFFILIATE_PROGRAM_ENABLEDShow the SolidInvoice Cloud affiliate program: a one-off prompt on the dashboard, a Refer & earn page in your profile and a link in the footer. Defaults to 1; set to 0 to hide all of it.
SOLIDINVOICE_AFFILIATE_PROMPT_DELAY_DAYSHow many days after finishing onboarding the dashboard prompt appears. Defaults to 3.
SOLIDINVOICE_AFFILIATE_SIGNUP_URLWhere the Join the affiliate program button leads. Defaults to https://billing.solidinvoice.co/affiliates.
SOLIDINVOICE_AFFILIATE_COMMISSIONThe recurring commission shown in the affiliate copy, as text. Defaults to 20%.
SOLIDINVOICE_AFFILIATE_YEARLY_EARNINGSThe most an affiliate earns per referred customer per year, shown in the affiliate headline. Defaults to $93.
SOLIDINVOICE_AFFILIATE_TERMS_URLLink to the affiliate terms on the Refer & earn page. Empty by default, which hides the link.

Other integrations (Sentry, Meilisearch, Google OAuth) have their own environment variables and are documented on their respective pages.

Updating​

  1. Stop the messenger worker: sudo systemctl stop solidinvoice-worker.service (or comment out the cron entry).
  2. Back up your database and the project directory.
  3. Download the new archive and replace the project files, keeping your .env.local and any custom changes.
  4. Run bin/console cache:clear --env=prod and bin/console doctrine:migrations:migrate --env=prod --no-interaction.
  5. Restart the worker.