Part 6 - Installing Composer and PDF Engine Considerations
- Invoice Ninja is created with Lavavel and to for Composer to work, we need to get copy Invoice Ninja to the working directory at /var/www/html/invoiceninja
- Critical: PDF Creation Engine - By default Invoice Ninja server comes with Phantom PDF (Phantom JS), a cloud based PDF creation engine. Phantom PDF seems to be required for VPS and containerized (Docker) server instances. It is optional for use on self-hosted setups like mine. The default configuration comes with the ability to create 100 PDF pages per day. If you decide to use Phantom PDF and need more than 100 pages per day, you can register here for a free API key that will provide creation of up to 500 PDF pages per day. The link is here at PhantomJs Cloud | Account Dashboard?
- My build uses the SnapPDF Engine and will disable the PhantomJS Engine, so in the next few steps, you can skip anything marked " Required for SnapPDF"
- (Required for SnapPDF) Installing the many things needed to make the SnapPDF engine work
sudo apt install libappindicator3-1 libdbusmenu-gtk3-4 libgbm-dev libgbm1 libindicator3-7 libwayland-server0 libxshmfence-dev gconf-service libasound2 libatk1.0-0 libcairo2 libgconf-2-4 libgdk-pixbuf2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 fonts-liberation libappindicator1 libnss3 xdg-utils
Part 7 - Installing Invoice Ninja
-
Stop Apache 2
sudo systemctl stop apache2
-
Create the working directory for Invoice Ninja
sudo mkdir /var/www/html/invoiceninja
-
Change to the newly created directory as the commands will be run from there
cd /var/www/html/invoiceninja
-
Download Invoice Ninja - Note the zip file is older then the current version so we can test the functionality of the update within Invoice Ninja. If you want to skip this, modify the URL in the nect command with the version number of the current release here at Releases ¡ invoiceninja/invoiceninja ¡ GitHub
sudo wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.1.62-release/invoiceninja.zip
-
(Optional) Display the downloaded invoiceninja.zip file in the /var/www/html/invoiceninja/ working directory
ls -la - We should see a file called invoiceninja.zip
-
Unzip the invoiceninja.zip file in the /var/www/html/invoiceninja/ working directory
sudo unzip invoiceninja.zip
Install and Run Composer
-
Installing composer is different than other things that have been installed earlier
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin âfilename=composer
-
You should get âŚ
All settings correct for using Composer
Downloading...
Composer (version 2.1.3) successfully installed to: /usr/local/bin/composer.phar
Use it: php /usr/local/bin/composer.phar
-
Use Composer to install Invoice Ninja in the working directory
sudo composer install --no-dev -o
-
Ignore the warning and install as sudo or the task will fail with the following error
[ErrorException]
file_put_contents(/var/www/html/invoiceninja/vendor/composer/autoload_classmap.php): Failed to open stream: Permission denied
-
Generate a new unique key, make sure to copy it somewhere during the .env configuration
sudo php artisan key:generate (Do not run this command more than once,especially after the system is live as the key it generates is unique. If there is an issue or you need to migrate data, loss of this key will cause issues)
-
Create a clean untouched backup of the .env file
sudo cp .env .env.oem.bak
-
Open the .env and edit
sudo nano .env
The .env file is the main configuration file for Invoice Ninja and contains lots of important stuff. The important things to configure are the username and password to the local SQL database (MariaDB) we configured earlier. Also because this example uses SnapPDF instead of PhantomJS, we need to disable Phantom. In the .env file we can also enable debugging and PDF debugging as those seem to be the things that break frequently
.env local database configuration
The default configuration looks like this
DB_HOST1=localhost
DB_DATABASE1=ninja
DB_USERNAME1=ninja
DB_PASSWORD1=ninja
DB_PORT1=3306
We need to change it to this - for the DB_PASSWORD field, substitute the password established during the setup of MariaDB.
DB_HOST1=localhost
DB_DATABASE1=invoiceninja
DB_USERNAME1=invoiceninjauser
DB_PASSWORD1=password1234!
DB_PORT1=3306
- Note: If you change the database password for the invoiceninjauser account in the future, you will need to update the password here in the .env file or Invoice Ninja canât communicate with the database.
- (Required for SnapPDF) Disabling PhantomJS to enable SnapPDF
Default configuration looks like this
#options - snappdf / phantom / hosted_ninja
PDF_GENERATOR=phantom
PHANTOMJS_KEY='a-demo-key-with-low-quota-per-ip-address'
PHANTOMJS_SECRET=secret
UPDATE_SECRET=secret
COMPOSER_AUTH='{"github-oauth": {"github.com": "${{ secrets.GITHUB_TOKEN }}"}}'
SENTRY_LARAVEL_DSN=https://cc7e8e2c678041689e53e409b7dba236@sentry.invoicing.co/5
Add the line PHANTOMJS_PDF_GENERATION=false and comment out the things related to PhantomJS. Also, we will add the line LOG_PDF_HTML=true for PDF debugging as the PDF seems to be sensitive to many things and breaks frequently. Make it look like this to disable PhantomJS and enable SnapPDF
#options - snappdf / phantom / hosted_ninja
#PDF_GENERATOR=phantom
#PHANTOMJS_KEY='a-demo-key-with-low-quota-per-ip-address'
#PHANTOMJS_SECRET=secret
UPDATE_SECRET=secret
PHANTOMJS_PDF_GENERATION=false
COMPOSER_AUTH='{"github-oauth": {"github.com": "${{ secrets.GITHUB_TOKEN }}"}}'
SENTRY_LARAVEL_DSN=https://cc7e8e2c678041689e53e409b7dba236@sentry.invoicing.co/5
LOG_PDF_HTML=true
- Save and close
- CRITICAL NOTE: Anytime the .env file is changed, or Invoice Ninja is updated to a new version, you need to run sudo php artisan optimize for the changes to take effect
- Update Artisan with new configuration
sudo php artisan optimize
Enabling Invoice Ninja in Apache
- Create a copy of the default website config for Invoice Ninja
sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/invoiceninja.conf
- Edit the newly created invoiceninja.conf file
sudo nano /etc/apache2/sites-available/invoiceninja.conf
Add at the top
<Directory /var/www/html/invoiceninja/public/>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
Change
DocumentRoot /var/www/html
To
DocumentRoot /var/www/html/invoiceninja/public
Should look like this
<Directory /var/www/html/invoiceninja/public/>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
<VirtualHost *:80>
# The ServerName directive sets the request scheme, hostname and port that
# the server uses to identify itself. This is used when creating
# redirection URLs. In the context of virtual hosts, the ServerName
# specifies what hostname must appear in the request's Host: header to
# match this virtual host. For the default virtual host (this file) this
# value is not decisive as it is used as a last resort host regardless.
# However, you must set it for any further virtual host explicitly.
# ServerName www.example.com
ServerAdmin xxxx@(your fake email address here)
ServerName ninja01.(your domain name here)
ServerAlias www.ninja01.(your domain name here)
DocumentRoot /var/www/html/invoiceninja/public
Redirect permanent "/" "https://ninja01.(your domain name here)/"
- Save and close the editor
- Edit the default-ssl.conf file
sudo nano /etc/apache2/sites-available/default-ssl.conf
Change
DocumentRoot /var/www/html
To
DocumentRoot /var/www/html/invoiceninja/public
Should look like this
<IfModule mod_ssl.c>
<VirtualHost _default_:443>
ServerAdmin your email address (alias or fake) here
ServerName ninja01.(your domain name here)
ServerAlias ninja01
DocumentRoot /var/www/html/invoiceninja/public
# Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
# error, crit, alert, emerg.
# It is also possible to configure the loglevel for particular
# modules, e.g.
#LogLevel info ssl:warn
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
# For most configuration files from conf-available/, which are
# enabled or disabled at a global level, it is possible to
# include a line for only one particular virtual host. For example the
# following line enables the CGI configuration for this host only
# after it has been globally disabled with "a2disconf".
#Include conf-available/serve-cgi-bin.conf
# SSL Engine Switch:
# Enable/Disable SSL for this virtual host.
SSLEngine on
# A self-signed (snakeoil) certificate can be created by installing
# the ssl-cert package. See
# /usr/share/doc/apache2/README.Debian.gz for more info.
# If both key and certificate are stored in the same file, only the
# SSLCertificateFile directive is needed.
SSLCertificateFile /etc/ssl/certs/apache-selfsigned.crt
SSLCertificateKeyFile /etc/ssl/private/apache-selfsigned.key
# SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
# SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
Add this at the bottom, save and close
* * * * * cd /var/www/html/invoiceninja && php artisan schedule:run >> /dev/null 2>&1
-
(Optional) display the cron job
sudo -u www-data crontab -l
-
Enable cron
sudo systemctl enable cron
-
(Optional) see if cron is running or restart cron
sudo systemctl status cron
sudo systemctl start cron
Ctrl + C to exit the status
-
Clean up the Apache and PHP test web page files from earlier
sudo mv /var/www/html/index.html /var/www/html/index.html.bak
sudo mv /var/www/html/phpinfo.php /var/www/html/phpinfo.php.bak
-
Set the owner and file permissions on the web root directories
sudo chown -R www-data:www-data /var/www/html/invoiceninja/
sudo chmod -R 755 /var/www/html/invoiceninja/
-
Disable the default site and enable the new Invoice Ninja site in Apache
sudo a2dissite 000-default.conf
sudo a2ensite invoiceninja.conf
-
Enable various modules for Apache to communicate with PHP
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.0-fpm
sudo a2dismod php8.0
sudo a2dismod mpm_prefork
sudo a2enmod mpm_event
-
Test the Apache configuration and reload Apache
sudo apache2ctl configtest
sudo systemctl restart apache2
sudo systemctl restart cron
Part 8 - Invoice Ninja v5 First Time Run Configuration
Open a local web browser and navigate to the system at https://ninja01/setup
If all went well during install, the first time run page will appear
- URL - Set this to the FQDN name of the server. Example https://ninja01.mydomain.com
- HTTPS should be checked by default
- (Opional) Reports - to forward data to the developers
- Test PDF to continue with the setup, you will need to press this button. If the PDF engine is broken, troubleshooting will be needed here
Troubleshooting Issues
- Log files are the place to see whats happening when things break
- Invoice Ninja Logs
nano /var/www/html/invoiceninja/storage/logs/laravel.log
Or
cat /var/www/html/invoiceninja/storage/logs/laravel.log
- Apache Logs
nano /var/log/apache2/error.log
Or
cat /var/log/apache2/error.log
Database Connection
- Even though this was configured earlier when we edited the .env, we still need to populate the info again. I consider this a design issue as the setup needs to communicate with the database before the setup is completed (circular reference?!). That is why we added the database info earlier
- Host: localhost (default)
- Port: 3306 (default)
- Database: invoiceninja (configured in the MariaDB setup earlier)
- Username: invoiceninjauser (configured in the MariaDB setup earlier)
- Password: (password established for invoiceninjauser during the MariaDB earlier)
- Test Connection when completed
Email Settings
-This will be specific to your email provider. I run my own mail servers, so your configuration may differ from mine
- Driver: SMTP
- From Name: (Name of your business or your name)
- From Address: (email address of the account you want to use for relaying emails through your email service or server)
- Username: (email address of the account you want to use for relaying emails through your email service or server, can be the same or different from the address set for From Address)
- Port: 587 (is standard for encrypted email communications)
- Password: (password for the username entered above)
- Encryption: STARTTLS (depends on your email host configuration)
- Send Test Email when completed to move to the last part of setup
User Details
- In this section we set the administrator account for the Invoice Ninja web console
- First Name: (Anything)
- Last Name: ( Anything)
- Email: (set a real email address for this field as it used for password resets and alerts)
- Agree to the Terms of Service and Terms Privacy Policy
- Submit to complete. It takes a few seconds even on fast systems for this to complete