Docker

Requirements

Install Docker on your machine;
Make sure Docker Compose is installed and available (it should be the case if you have chosen to install Docker via Docker Desktop); and
Make sure Git is installed on your machine.

Run the Lago App

Run the app with a one-click Docker command

You can start using the app by using a one-click Docker command in a shell:

docker run -d --name lago -p 80:80 -p 3000:3000 getlago/lago:latest

You can now open your browser and go to http://localhost to connect to the application. Just after signing up, Lago’s API is exposed at http://localhost:3000.

Run the app with advanced Docker commands

If you don’t want to use the one-click Docker command, you can start using Lago by running more advanced commands in a shell:

# Get the code
git clone https://github.com/getlago/lago.git

# Go to Lago folder
cd lago

# Set up environment configuration
echo "LAGO_RSA_PRIVATE_KEY=\"`openssl genrsa 2048 | base64 | tr -d '\n'`\"" >> .env

source .env

# Start all the components
docker compose up

You can now open your browser and go to http://localhost to connect to the application. Just after signing up, Lago’s API is exposed at http://localhost:3000.

Signing up

It’s mandatory to create your organization by signing up to Lago. This organization is the core object of your biller as it’s used to invoice your customers.

Write down your organization name;
Use the main billing email of your company; and
Define the admin password for this email.

You will be able to invite other email addresses within the application. If you already have an account, you can also log in. Once you are able to access the app, you can retrieve your API key.

Find your API Key

Your API Key can be found directly in the UI:

Access the Developer section from the sidebar;
The first tab of this section is related to your API keys; and
Click the Copy button to copy it to clipboard.

Configuration

Version

Docker images are always updated to the last stable version in the docker-compose.yml file. You can use a different tag if needed by checking the releases list.

We recommend to avoid the usage of latest tag, you should use the last tagged version, you can track what are the last version on Dockerhub

lago-api : https://hub.docker.com/repository/docker/getlago/api
lago-front : https://hub.docker.com/repository/docker/getlago/front

Environment variables

Lago uses the following environment variables to configure the components of the application. You can override them to customise your setup.

Variable	Default value	Description
`POSTGRES_HOST`	db	(With Docker compose) Host name of the postgres server
`POSTGRES_DB`	lago	(With Docker compose) Name of the postgres database
`POSTGRES_USER`	lago	(With Docker compose) Database user for postgres connection
`POSTGRES_PASSWORD`	changeme	(With Docker compose) Database password for postgres connection
`POSTGRES_PORT`	5432	(With Docker compose) Port the postgres database listens to
`POSTGRES_SCHEMA`	public	Name of the postgres schema
`DATABASE_URL`		(Without docker compose) Full url to the postgres server
`DATABASE_POOL`	10	Max number of connection opened to the postgres database per api, worker and clock instances
`DATABASE_PREPARED_STATEMENTS`	true	Enable or disable prepared statements in the postgres database
`REDIS_HOST`	redis	Host name of the redis server
`REDIS_PORT`	6379	Port the redis database listens to
`REDIS_PASSWORD`		Password of the redis server
`LAGO_REDIS_CACHE_HOST`	redis	Host name of the redis cache server
`LAGO_REDIS_CACHE_PORT`	6379	Port the redis cache server listens to
`LAGO_REDIS_CACHE_PASSWORD`		Password of the redis cache server
`LAGO_REDIS_CACHE_POOL_SIZE`	5	Max number of connections in the redis cache connection pool
`LAGO_MEMCACHE_SERVERS`		Coma separated list of memcache servers
`LAGO_FRONT_URL`	http://localhost	URL of the Lago front-end application.Used for CORS configuration
`FRONT_PORT`	80	Port the front-end application listens to
`LAGO_API_URL`	http://localhost:3000	URL of the Lago back-end application
`API_URL`	http://localhost:3000	URL of the Lago back-end application defined for the front image
`API_PORT`	3000	Port the back-end application listens to
`SECRET_KEY_BASE`	your-secret-key-base-hex-64	Secret key used for session encryption
`SENTRY_DSN`		Sentry DSN key for error and performance tracking on Lago back-end
`SENTRY_DSN_FRONT`		Sentry DSN key for error and performance tracking on Lago front-end
`LAGO_RSA_PRIVATE_KEY`		Private key used for webhook signatures
`LAGO_SIDEKIQ_WEB`		Activate the Sidekiq web UI, disabled by default
`LAGO_ENCRYPTION_PRIMARY_KEY`	your-encryption-primary-key	Encryption primary key used to secure sensitive values stored in the database
`LAGO_ENCRYPTION_DETERMINISTIC_KEY`	your-encryption-deterministic-key	Encryption deterministic key used to secure sensitive values stored in the database
`LAGO_ENCRYPTION_KEY_DERIVATION_SALT`	your-encryption-derivation-salt	Encryption key salt used to secure sensitive values stored in the database
`LAGO_WEBHOOK_ATTEMPTS`	3	Number of failed attempt before stopping to deliver a webhook
`LAGO_USE_AWS_S3`	false	Use AWS S3 for files storage
`LAGO_AWS_S3_ACCESS_KEY_ID`	azerty123456	AWS Access Key id that has access to S3
`LAGO_AWS_S3_SECRET_ACCESS_KEY`	azerty123456	AWS Secret Access Key that has access to S3
`LAGO_AWS_S3_REGION`	us-east-1	AWS S3 Region
`LAGO_AWS_S3_BUCKET`	bucket	AWS S3 Bucket name
`LAGO_AWS_S3_ENDPOINT`		S3 compatible storage endpoint. Should be set only if you are using another storage provider than AWS S3
`LAGO_USE_GCS`	false	Use Google Cloud Service Cloud Storage for file storage, ⚠️ If you want to use GCS, you have to pass the credentials json key file to the api and worker service
`LAGO_GCS_PROJECT`		GCS Project name
`LAGO_GCS_BUCKET`		GCS Bucket Name
`LAGO_PDF_URL`	http://pdf:3000	PDF Service URL on your infrastructure
`LAGO_DISABLE_SIGNUP`		Disable Sign up when running Lago in self-hosted
`LAGO_RAILS_STDOUT`	true	Set to true to activate logs on containers
`LAGO_DISABLE_WALLET_REFRESH`		Disable automatic refresh of wallet ongoing balance
`LAGO_DISABLE_PDF_GENERATION`	false	Disable automatic PDF generation for invoices, credit notes, and receipts. As a result, the corresponding download endpoints will be unavailable
`GOOGLE_AUTH_CLIENT_ID`		Client ID for Google auth Single Sign On
`GOOGLE_AUTH_CLIENT_SECRET`		Client Secret for Google auth Single Sign On

We recommend that you change POSTGRES_PASSWORD, SECRET_KEY_BASE, LAGO_RSA_PRIVATE_KEY, LAGO_ENCRYPTION_PRIMARY_KEY, LAGO_ENCRYPTION_DETERMINISTIC_KEY and LAGO_ENCRYPTION_KEY_DERIVATION_SALT to improve the security of your Lago instance:

SECRET_KEY_BASE can be generated using the openssl rand -hex 64 command.
LAGO_RSA_PRIVATE_KEY can be generated using the openssl genrsa 2048 | base64 command.
LAGO_ENCRYPTION_PRIMARY_KEY, LAGO_ENCRYPTION_DETERMINISTIC_KEY and LAGO_ENCRYPTION_KEY_DERIVATION_SALT can all be gerated using the cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1 command.

Components

Lago uses the following containers:

Container	Role
`front`	Front-end application
`api`	API back-end application
`api_worker`	Asynchronous worker for the API application
`api_clock`	Clock worker for the API application
`db`	Postgres database engine used to store application data
`redis`	Redis database engine used as a queuing system for asynchronous tasks
`pdf`	PDF generation powered by Gotenberg

You can also use your own database or Redis server. To do so, remove the db and redis configurations from the docker-compose.yml file and update the environment variables accordingly.

SSL Support

Lago Front application can be configured to support SSL certificates. You have two options to achieve this:

by using a self-signed certificate
by using a signed certificate generated by Let’s Encrypt

Self Signed Certificate

Run the script to generate the certificates

# Be sure to be in your lago folder
./extra/init-selfsigned.sh

# This should create certificates in the ./extra/ssl/ folder

Take a look at the docker-compose.yml file and uncomment the part related to the Self-Signed certificate

volumes:
  - ./extra/nginx-selfsigned.conf:/etc/nginx/conf.d/default.conf
  - ./extra/ssl/nginx-selfsigned.crt:/etc/ssl/certs/nginx-selfsigned.crt
  - ./extra/ssl/nginx-selfsigned.key:/etc/ssl/private/nginx-selfsigned.key
  - ./extra/ssl/dhparam.pem:/etc/ssl/certs/dhparam.pem

You can now start the front application with a self signed SSL certificate support

docker-compose up front

Let’s Encrypt Certificate

Edit the file extra/init-letsencrypt.sh
- You must replace lago.example with your domain name
- You must enter a valid email address
Edit the file extra/nginx-letsencrypt.conf
- You must replace lago.example with your domain name
Uncomment the Cerbot lines in the docker-compose.yml file
Run the following script

# Be sure to be in your lago folder
./extra/init-letsencrypt.sh

# You will be asked to provide some information
# After that you should be able to see the extra/certbot folder

Take a look at the docker-compose.yml file and uncomment all the parts related to the Let’s Encrypt’s support

command:
  '/bin/sh -c ''while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx
  -g "daemon off;"'''
---
volumes:
  - ./extra/nginx-letsencrypt.conf:/etc/nginx/conf.d/default.conf
  - ./extra/certbot/conf:/etc/letsencrypt
  - ./extra/certbot/www:/var/www/certbot

You can now start the front application with the signed certificate support

docker-compose up front

Storage

By default, Lago uses the internal storage of the container. You can customize it by defining different environment variables. We currently support :

AWS S3
AWS S3 Compatibles Endpoints
Google Cloud Service Cloud Storage

If you use S3 compatibles endpoints, you should set the LAGO_AWS_S3_REGION to a default value (ei: us-east-1), it is required to work properly!

AWS S3

You have to set these variables to use AWS S3.

Name	Description
`LAGO_USE_AWS_S3`	Set to “true” if you want to use AWS S3
`LAGO_AWS_S3_ACCESS_KEY_ID`	AWS S3 Credentials Access Key Id
`LAGO_AWS_S3_SECRET_ACCESS_KEY`	AWS S3 Credentials Secret Access Key
`LAGO_AWS_S3_REGION`	AWS S3 Region
`LAGO_AWS_S3_BUCKET`	AWS S3 Bucket

AWS S3 Compatible Endpoints

You have to set these variables to use AWS S3 Compatible Endpoints.

Name	Description
`LAGO_USE_AWS_S3`	Set to “true” if you want to use AWS S3 Compatible Endpoints
`LAGO_AWS_S3_ENDPOINT`	AWS S3 Compatible Endpoint
`LAGO_AWS_S3_ACCESS_KEY_ID`	AWS S3 Credentials Access Key Id
`LAGO_AWS_S3_SECRET_ACCESS_KEY`	AWS S3 Credentials Secret Access Key
`LAGO_AWS_S3_BUCKET`	AWS S3 Bucket
`LAGO_AWS_S3_REGION`	Not used but required by the AWS SDK

Google Cloud Service Cloud Storage

You have to set those variables to use GCS Cloud Storage.

Name	Description
`LAGO_USE_GCS`	Set to “true” if you want to use GCS Cloud Storage
`LAGO_GCS_PROJECT`	GCS Project name
`LAGO_GCS_BUCKET`	GCS Bucket name

In the docker-compose.yml file, you must uncomment the lines and pass the correct GCS credentials json file.

api:
  volumes:
    - gcs_keyfile.json:/app/gcs_keyfile.json

api-worker:
  volumes:
    - gcs_keyfile.json:/app/gcs_keyfile.json

SMTP Configuration

In order to use the email feature, you need to configure some environment variables.

In addition to this configuration, defining an organization email in Settings > Organization is mandatory; without it, emails will not be sent.

Name	Description
`LAGO_FROM_EMAIL`	Required to send emails (i.e: noreply@getlago.com)
`LAGO_SMTP_ADDRESS`	Address of the SMTP server
`LAGO_SMTP_PORT`	Port of the SMTP Server
`LAGO_SMTP_USERNAME`	Username of the SMTP Server
`LAGO_SMTP_PASSWORD`	Password of the SMTP Server

Single Sign On using Google authentication

In order to enable Google authentication for single sign on, you have to set those variables.

Name	Description
`GOOGLE_AUTH_CLIENT_ID`	Client ID for Google auth Single Sign On
`GOOGLE_AUTH_CLIENT_SECRET`	Client Secret for Google auth Single Sign On

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Invoicing

Payments & Cash Collection

Data & Analytics

Resources

Requirements

Run the Lago App

Run the app with a one-click Docker command

Run the app with advanced Docker commands

Signing up

Find your API Key

Configuration

Version

Environment variables

Components

SSL Support

Self Signed Certificate

Let’s Encrypt Certificate

Storage

AWS S3

AWS S3 Compatible Endpoints

Google Cloud Service Cloud Storage

SMTP Configuration

Single Sign On using Google authentication

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Invoicing

Payments & Cash Collection

Data & Analytics

Resources

​Requirements

​Run the Lago App

​Run the app with a one-click Docker command

​Run the app with advanced Docker commands

​Signing up

​Find your API Key

​Configuration

​Version

​Environment variables

​Components

​SSL Support

​Self Signed Certificate

​Let’s Encrypt Certificate

​Storage

​AWS S3

​AWS S3 Compatible Endpoints

​Google Cloud Service Cloud Storage

​SMTP Configuration

​Single Sign On using Google authentication

Requirements

Run the Lago App

Run the app with a one-click Docker command

Run the app with advanced Docker commands

Signing up

Find your API Key

Configuration

Version

Environment variables

Components

SSL Support

Self Signed Certificate

Let’s Encrypt Certificate

Storage

AWS S3

AWS S3 Compatible Endpoints

Google Cloud Service Cloud Storage

SMTP Configuration

Single Sign On using Google authentication