-
-
Notifications
You must be signed in to change notification settings - Fork 615
docs(deploy): improve VPS/reverse-proxy guidance and fix deploy.sh #713
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
vivek-tiwari-vt
wants to merge
2
commits into
getlago:main
Choose a base branch
from
vivek-tiwari-vt:codex/issue-444-deploy-guides
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,175 +1,171 @@ | ||
| # Lago Deploy | ||
|
|
||
| This repository contains the necessary files to deploy the Lago project. | ||
| This directory contains deployment templates for self-hosting Lago with Docker Compose, including VPS and reverse-proxy friendly setups. | ||
|
|
||
| ## Docker Compose Local | ||
| ## Deployment modes | ||
|
|
||
| To deploy the project locally, you need to have Docker and Docker Compose installed on your machine. | ||
| This configuration can be used for small production usages but it's not recommended for large scale deployments. | ||
| | Mode | Best for | SSL / Reverse proxy | Files | | ||
| | --- | --- | --- | --- | | ||
| | Quickstart | Fast evaluation on one host | No | `docker run` | | ||
| | Local | Local testing and staging | No | `docker-compose.local.yml` | | ||
| | Light | Small production workloads | Yes (Traefik + Let's Encrypt) | `docker-compose.light.yml` + `.env.light.example` | | ||
| | Production | Higher throughput production | Yes (Traefik + Let's Encrypt) | `docker-compose.production.yml` + `.env.production.example` | | ||
|
|
||
| ### Get Started | ||
| ## Prerequisites | ||
|
|
||
| 1. Get the docker compose file | ||
| 1. Docker engine installed | ||
| 2. Docker Compose (`docker compose` plugin or `docker-compose`) | ||
| 3. For `Light` and `Production`: a public domain with valid DNS A/AAAA records | ||
| 4. For `Light` and `Production`: port `443` reachable from the internet (`8080` is used for Traefik dashboard/health checks) | ||
|
|
||
| ```bash | ||
| curl -o docker-compose.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.local.yml | ||
| ``` | ||
| ## Option A: Interactive deploy script | ||
|
|
||
| 2. Run the following command to start the project: | ||
| Use the guided deploy script when you want the quickest path on a VPS: | ||
|
|
||
| ```bash | ||
| docker compose up --profile all | ||
|
|
||
| # If you want to run it in the background | ||
| docker compose up -d --profile all | ||
| curl -fsSL -o deploy.sh https://raw.githubusercontent.com/getlago/lago/main/deploy/deploy.sh | ||
| bash deploy.sh | ||
| ``` | ||
|
|
||
| ## Docker Compose Light | ||
| The script lets you choose the deployment mode, downloads the right files, asks for required environment variables, and starts the stack. | ||
|
|
||
| This configuration provide Traefik as a reverse proxy to ease your deployment. | ||
| It supports SSL with Let's Encrypt. :warning: You need a valid domain (with at least one A or AAA record)! | ||
| ## Option B: Manual Docker Compose deployment | ||
|
|
||
| 1. Get the docker compose file | ||
| ### Local mode | ||
|
|
||
| ```bash | ||
| curl -o docker-compose.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.light.yml | ||
| curl -o .env https://raw.githubusercontent.com/getlago/lago/main/deploy/.env.light.example | ||
| curl -fsSL -o docker-compose.local.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.local.yml | ||
| docker compose -f docker-compose.local.yml up -d --profile all | ||
| ``` | ||
|
|
||
| 2. Replace the .env values with yours | ||
| ### Light mode (VPS + reverse proxy + TLS) | ||
|
|
||
| ```bash | ||
| LAGO_DOMAIN=domain.tld | ||
| LAGO_ACME_EMAIL=email@domain.tld | ||
| curl -fsSL -o docker-compose.light.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.light.yml | ||
| curl -fsSL -o .env https://raw.githubusercontent.com/getlago/lago/main/deploy/.env.light.example | ||
| ``` | ||
|
|
||
| 3. Run the following command to start the project | ||
| Set `.env`: | ||
|
|
||
| ```bash | ||
| docker compose up --profile all | ||
|
|
||
| # If you want to run it in the background | ||
| docker compose up -d --profile all | ||
| LAGO_DOMAIN=billing.example.com | ||
| LAGO_ACME_EMAIL=infra@example.com | ||
| ``` | ||
|
|
||
| ## Docker Compose Production | ||
| Run: | ||
|
|
||
| ```bash | ||
| docker compose -f docker-compose.light.yml up -d --profile all | ||
| ``` | ||
|
|
||
| This configuration provide Traefik as a reverse proxy to ease your deployment. | ||
| It supports SSL wth Let's Encrypt. :warning: You need a valid domain (with at least one A or AAA record)! | ||
| It also adds multiple services that will help your to handle more load. | ||
| Portainer is also packed to help you scale services and manage your Lago stack. | ||
| ### Production mode | ||
|
|
||
| ```bash | ||
| curl -o docker-compose.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.production.yml | ||
| curl -o .env https://raw.githubusercontent.com/getlago/lago/main/deploy/.env.production.example | ||
| curl -fsSL -o docker-compose.production.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.production.yml | ||
| curl -fsSL -o .env https://raw.githubusercontent.com/getlago/lago/main/deploy/.env.production.example | ||
| ``` | ||
|
|
||
| 2. Replace the .env values with yours | ||
| Set `.env`: | ||
|
|
||
| ```bash | ||
| LAGO_DOMAIN=domain.tld | ||
| LAGO_ACME_EMAIL=email@domain.tld | ||
| LAGO_DOMAIN=billing.example.com | ||
| LAGO_ACME_EMAIL=infra@example.com | ||
| PORTAINER_USER=lago | ||
| PORTAINER_PASSWORD=changeme | ||
| PORTAINER_PASSWORD=change-me | ||
| ``` | ||
|
|
||
| 3. Run the following command to start the project | ||
| Run: | ||
|
|
||
| ```bash | ||
| docker compose up --profile all | ||
|
|
||
| # If you want to run it in the background | ||
| docker compose up -d --profile all | ||
| docker compose -f docker-compose.production.yml up -d --profile all | ||
| ``` | ||
|
|
||
| ## VPS and reverse-proxy checklist | ||
|
|
||
| 1. Point DNS to your VPS (`A`/`AAAA` record for `LAGO_DOMAIN`) | ||
| 2. Open inbound port `443` (and `8080` only if you expose Traefik dashboard/health checks) | ||
| 3. Use `Light` or `Production` mode (both ship with Traefik) | ||
| 4. Set `LAGO_DOMAIN` and `LAGO_ACME_EMAIL` in `.env` | ||
| 5. Start with `--profile all` (or selective profiles below) | ||
| 6. Verify `https://<LAGO_DOMAIN>` and `https://<LAGO_DOMAIN>/api` | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Profiles | ||
|
|
||
| The docker compose file contains multiple profiles to enable or disable some services. | ||
| Here are the available profiles: | ||
| - `all`: Enable all services | ||
| - `all-no-pg`: Disable the PostgreSQL service | ||
| - `all-no-redis`: Disable the Redis service | ||
| - `all-no-keys`: Disable the RSA keys generation service | ||
| The compose files support these profiles: | ||
|
|
||
| This allow you to start only the service you want to use, please see the following sections for more information. | ||
|
|
||
| ```bash | ||
| # Start all services | ||
| docker compose up --profile all | ||
| - `all`: enable all services | ||
| - `all-no-pg`: disable PostgreSQL (use external PostgreSQL) | ||
| - `all-no-redis`: disable Redis (use external Redis) | ||
| - `all-no-db`: disable PostgreSQL and Redis | ||
| - `all-no-keys`: disable RSA key generation | ||
|
|
||
| # Start without PostgreSQL | ||
| docker compose up --profile all-no-pg | ||
| Examples: | ||
|
|
||
| # Start without Redis | ||
| docker compose up --profile all-no-redis | ||
| ```bash | ||
| # Without PostgreSQL | ||
| docker compose -f docker-compose.light.yml up -d --profile all-no-pg | ||
|
|
||
| # Start without PostgreSQL and Redis | ||
| docker compose up --profile all-no-db | ||
| # Without Redis | ||
| docker compose -f docker-compose.light.yml up -d --profile all-no-redis | ||
|
|
||
| # Start without RSA keys generation | ||
| docker compose up --profile all-no-keys | ||
| # Without PostgreSQL and Redis | ||
| docker compose -f docker-compose.light.yml up -d --profile all-no-db | ||
|
|
||
| # Start without PostgreSQL, Redis and RSA keys generation | ||
| docker compose up | ||
| # Without generated RSA key | ||
| docker compose -f docker-compose.light.yml up -d --profile all-no-keys | ||
| ``` | ||
|
|
||
| ### PostgreSQL | ||
|
|
||
| It is possible to disable the usage of the PostgreSQL database to use an external database instance. | ||
| ### External PostgreSQL | ||
|
|
||
| 1. Set those environment variables: | ||
| Set: | ||
|
|
||
| - `POSTGRES_HOST` | ||
| - `POSTGRES_PORT` | ||
| - `POSTGRES_USER` | ||
| - `POSTGRES_PASSWORD` | ||
| - `POSTGRES_DB` | ||
| - `POSTGRES_HOST` | ||
| - `POSTGRES_PORT` | ||
| - `POSTGRES_SCHEMA` optional | ||
|
|
||
| 2. Run the following command to start the project without PostgreSQL: | ||
|
|
||
| ```bash | ||
| docker compose up --profile all-no-pg | ||
| ``` | ||
| - `POSTGRES_SCHEMA` (optional) | ||
|
|
||
| ### Redis | ||
| Then run with `--profile all-no-pg`. | ||
|
|
||
| It is possible to disable the usage of the Redis database to use an external Redis instance. | ||
| ### External Redis | ||
|
|
||
| 1. Set those environment variables: | ||
| Set: | ||
|
|
||
| - `REDIS_HOST` | ||
| - `REDIS_PORT` | ||
| - `REDIS_PASSWORD` optional | ||
| - `REDIS_PASSWORD` (optional) | ||
|
|
||
| 2. Run the following command to start the project without Redis: | ||
| Then run with `--profile all-no-redis`. | ||
|
|
||
| ```bash | ||
| docker compose up --profile all-no-redis | ||
| ``` | ||
| ### RSA key management | ||
|
|
||
| By default, compose generates an RSA key pair used for JWT signing. To provide your own key: | ||
|
|
||
| ### RSA Keys | ||
| 1. Remove the `lago_rsa_data` volume | ||
| 2. Generate a key with `openssl genrsa 2048 | openssl base64 -A` | ||
| 3. Set `LAGO_RSA_PRIVATE_KEY` | ||
| 4. Start with `--profile all-no-keys` | ||
|
|
||
| Those docker compose file generates an RSA Keys pair for the JWT tokens generation. | ||
| You can find the keys in the `lago_rsa_data` volume or in the `/app/config/keys` directory in the backends containers. | ||
| If you do not want to use those keys: | ||
| - Remove the `lago_rsa_data` volume | ||
| - Generate your own key using `openssl genrsa 2048 | openssl base64 -A` | ||
| - Export this generated key to the `LAGO_RSA_PRIVATE_KEY` env var. | ||
| - Run the following command to start the project without the RSA keys generation: | ||
| All backend services must share the same private key. | ||
|
|
||
| ### Apply `.env` changes safely | ||
|
|
||
| When changing public URL variables (`LAGO_DOMAIN`, `LAGO_API_URL`, `LAGO_FRONT_URL`, `API_URL`), recreate the impacted services so runtime config is regenerated: | ||
|
|
||
| ```bash | ||
| docker compose up --profile all-no-keys | ||
| docker compose -f <compose-file>.yml down | ||
| docker compose -f <compose-file>.yml up -d --profile all | ||
| ``` | ||
|
Comment on lines
+154
to
161
|
||
|
|
||
| *All BE Services use the same RSA key, they will exit immediately if no key is provided.* | ||
| Use the same compose file you started with (for example `docker-compose.light.yml` or `docker-compose.production.yml`). | ||
|
|
||
| ## Monitoring | ||
|
|
||
| For production deployments, we recommend setting up monitoring for Sidekiq workers. See the [Monitoring documentation](../docs/monitoring.md) for: | ||
| - Prometheus metrics endpoints and available metrics | ||
| For production deployments, set up Sidekiq monitoring. See [Monitoring documentation](../docs/monitoring.md) for: | ||
|
|
||
| - Prometheus metrics and available metrics | ||
| - Recommended alerting rules | ||
| - Grafana dashboard recommendations | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The checklist says to open inbound ports
80and443, but the currentLight/ProductionTraefik setup only binds443(TLS challenge). Either remove80from the checklist or explain when/why80is needed (e.g., if adding an HTTP->HTTPS redirect entrypoint).