Programster's Blog

Tutorials focusing on Linux, programming, and open source

Docker Deploy Invoice Ninja

The easiest way to deploy Invoice Ninja is through docker which I will show you below. However if you wish to manually deploy it, this guide might be useful.

Requirements

I managed to deploy on a VM with only 512 MB of RAM. However, because we will be using a database container, and MySQL has a habbit of growing in memory, I would recommend deploying on a 1GB instance.

Steps

Install docker.

Install docker-compose.

Grab the example.

mkdir $HOME/invoice-ninja
cd $HOME/invoice-ninja
git clone https://github.com/invoiceninja/dockerfiles.git
mv dockerfiles/example/.env dockerfiles/example/env
mv dockerfiles/example/* .
rm -rf dockerfiles

You should now have a folder called invoice-ninja in your home directory which contains the following files:

  • docker-compose.yml
  • env
  • nginx.conf

Edit Environment Variables

The env file will look like below (unless it has changed since I wrote this tutorial).

APP_DEBUG=1
APP_URL=http://localhost:8000
APP_KEY=SomeRandomStringSomeRandomString
APP_CIPHER=AES-256-CBC
DB_USERNAME=root
DB_PASSWORD=pwd
DB_HOST=mysql
MAIL_HOST=mail.service.host
MAIL_USERNAME=username
MAIL_PASSWORD=password
MAIL_DRIVER=smtp
MAIL_FROM_NAME="My name"
MAIL_FROM_ADDRESS=user@mail.com

It's very important to edit this file and do the following:

  • Change APP_DEBUG to 0
  • Change the APP_URL to your hostname or IP and remove the port 8000
  • Change APP_KEY to a random string of your making.
    • I recommend using the command openssl rand -base64 24 to generate a random one that is the right length.
  • Change DB_PASSWORD to something else.
  • Update the MAIL_ items to your SMTP details.

By the end of it, you should have something like:

APP_DEBUG=0
APP_URL=http://my.site.com
APP_KEY=r+BvncSxAf+fQXYUxSW6wXbSvsOL+Ns5
APP_CIPHER=AES-256-CBC
DB_USERNAME=root
DB_PASSWORD=thecrazydogchasesparkedcars
DB_HOST=mysql
MAIL_HOST=smtp.gmail.com
MAIL_USERNAME=username@gmail.com
MAIL_PASSWORD=myAppSpecificPassword
MAIL_DRIVER=smtp
MAIL_FROM_NAME="Programster Page"
MAIL_FROM_ADDRESS=username@gmail.com

Edit docker-compose.yml

Now go into your docker-compose.yml file and change:

  • the database password to match whatever you set in the env file in the previous step.
  • .env to env.
  • the port line from 8000:80 to 80:80.
    • This will allow the site to be available without needing to enter a port into the URL bar.

I made the env file a non-hidden file so that it is not accidentally forgotten about as it's fairly important as it contains your passwords etc.

Deploy!

Now you can deploy with the following command:

docker-compose up

Web UI Setup

Now navigate to your server's IP or hostname and you should be presented with a form to fill in like below:

Most of the details should already be filled in for you (from the environment file earlier). You just need to enter your name details and submit. It would be a good idea to make use of button to send a test email to check your SMTP details are correct. If you do not see this screen please refer to the debugging section below.

State

All state is held in the database, with the application layer holding nothing. Our database is a container that creates a volume in our directory under $HOME/invoice-ninja/var/mysql. Do not delete this folder unless you wish to "reset".

Debugging

If you do not see the Web UI Setup form then something went wrong. It would be a good idea to re-deploy with APP_DEBUG set to 1 and then you will get an error message in the web interface. It is also good to read the text that appears in the CLI after you ran docker-compose up.

Common issues are:

  • Database password not matching in the compose file and the environment file.
  • The APP_KEY string not being long enough.

Conclusion

You should now have your own open source invoice solution. In future I will show how to get SSL enabled.