Skip to content

Development Environment

Jump to bottom
Julien Bourdeau edited this page Feb 3, 2025 · 19 revisions

If you want to have a nice Lago Development Environment, you can follow this guide on how to make it works on your machine.

NOTE: This documentation is intended for people willing to contribute to Lago. If you want to try Lago on your local system, we encourage your to look at the Lago public documentation.

Requirements

  • Git
  • Docker
  • Homebrew (macOS only) 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • OpenSSL 
    # Ubuntu/Debian
sudo apt update
sudo apt install openssl

# MAC OS
brew install openssl

Local Environment Setup

  • First of all, you need to clone the Lago repo on your machine, since we're using Git submodules, here is the good command to do it
git clone --recurse-submodules [email protected]:getlago/lago.git
cd lago

# If you're not using bash, replace .bashrc with your shell rc, ei: ~/.zshrc
echo "export LAGO_PATH=${PWD}" >> ~/.bashrc
echo 'alias lago="docker-compose -f $LAGO_PATH/docker-compose.dev.yml"' >> ~/.bashrc
source ~/.bashrc
  • Install mkcert and generate some certs for TLS usage
brew install mkcert nss
mkcert -install
cd $LAGO_PATH/traefik
mkdir certs
cd certs
mkcert -cert-file lago.dev.pem -key-file lago.dev-key.pem lago.dev "*.lago.dev"
  • Add all custom domains to your /etc/hosts file
127.0.0.1 traefik.lago.dev
127.0.0.1 api.lago.dev
127.0.0.1 app.lago.dev
127.0.0.1 pdf.lago.dev
127.0.0.1 license.lago.dev
127.0.0.1 mail.lago.dev
  • Setup API
cp ./api/.env.dist ./api/.env
touch ./api/config/master.key

Local Environment Commands

  • Start your local environment
lago up -d db redis traefik mailhog clickhouse
lago up front api api-worker api-clock pdf

  • Start enjoying your local Lago at https://app.lago.dev

  • Start the Rails console with lago exec api bin/rails console

Environment Variables

Docker services will rely on .env.development.default to find all the necessary env variable. You can override any variable in .env.development.

Example: If you want to disable Clickhouse, you can set LAGO_CLICKHOUSE_ENABLED=false in your .env.development, which will override the default value set in .env.default

NOTE: .env.development.default is version with git but .env.development is ignored.

If you have defined env variable in your shell (like .zshrc), you can't use `ENV_VAR=${ENV_VAR_FROM_SHELL} anymore. The docker .env files are not interpolated so make sure all values are final.

Seeding your DB

To ensure your own user is created when starting the app, define the following vars to your ./.env.development file:

LAGO_CREATE_ORG=true
[email protected]
LAGO_ORG_USER_PASSWORD=password
LAGO_ORG_NAME=Acme
LAGO_ORG_API_KEY=lago_key_1234567890

If you want to execute all the seeders in ./api/db/seeders/ run lago exec api bin/rails db:seed

Dedicated queue

Lago can define dedicated queues for certain jobs. This is controlled with env variables like SIDEKIQ_EVENTS for instance. If you enable a dedicated queue in .env.development, make sure to run the associated queue worker.

# If SIDEKIQ_EVENTS=true
# Run:
lago api-events-worker

Setup license service

Follow instructions at https://github.com/getlago/lago-license

Update your local copy of the code

git pull --recurse-submodules
Clone this wiki locally