docs(deploy): improve VPS/reverse-proxy guidance and fix deploy.sh

[vivek-tiwari-vt]

Summary

• improve self-host deployment documentation for non-localhost setups (VPS + reverse proxy)
• add explicit guidance for Local, Light, and Production deployment modes
• add a VPS/reverse-proxy checklist and safe .env change/recreate flow
• fix deploy/deploy.sh compose detection/execution and compose file selection bugs

Why

Issue #444 highlights a documentation gap for users deploying Lago outside localhost, especially on VPS environments behind a proxy.

Validation

• bash -n deploy/deploy.sh

closes #444

[Copilot]

Pull request overview

This PR updates Lago’s self-host deployment guidance to better support VPS and reverse-proxy setups, and refactors deploy/deploy.sh to improve Docker Compose detection and compose-file selection for different deployment modes.

Changes:

• Expanded deploy/README.md to document Quickstart, Local, Light, and Production modes, plus a VPS/reverse-proxy checklist and safer .env change guidance.
• Updated deploy/deploy.sh to detect docker compose vs docker-compose, centralize compose execution, and download mode-specific compose files.
• Updated the root README.md to point users to the deployment templates for VPS/reverse-proxy setups.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
deploy/deploy.sh	Adds compose detection/helpers and mode-specific compose file handling for scripted deployments
deploy/README.md	Reworks self-host docs for VPS/reverse-proxy + mode-specific instructions
README.md	Reframes deployment section and links to deploy/README.md for non-localhost setups

Comments suppressed due to low confidence (2)

deploy/deploy.sh:282

• The DNS check runs before loading values from the existing .env file (and before prompting the user). In most runs LAGO_DOMAIN will only be present in .env, so check_domain_dns will be skipped and invalid domains won't be caught. Load .env (or prompt for LAGO_DOMAIN) before running the DNS check, or re-run the check after collecting the variable.

# Check Env Vars depending on the deployment
if [[ "$selected_key" == "Light" || "$selected_key" == "Production" ]]; then
    mandatory_vars=("LAGO_DOMAIN" "LAGO_ACME_EMAIL")
    if [[ "$selected_key" == "Production" ]]; then
        mandatory_vars+=("PORTAINER_USER" "PORTAINER_PASSWORD")
    fi
    external_pg=false
    external_redis=false

    if [[ -n "$LAGO_DOMAIN" ]]; then
        check_domain_dns "$LAGO_DOMAIN"
        if [[ $? -eq 1 ]] && ! ask_yes_no "No valid DNS record found. Continue anyway?"; then

deploy/deploy.sh:252

• In the Light/Production download steps, the success check ($?) only reflects the exit code of the last curl (the .env download), so the script may proceed even if the compose file download failed. Also, using curl -s without -f can still return success on HTTP errors (e.g., 404). Check both downloads explicitly and use curl -fS (or -fsSL) so HTTP failures are detected.

        echo "${CYAN}${BOLD}🚀 Downloading Light deployment files...${NORMAL}"
        COMPOSE_FILE="docker-compose.light.yml"
        curl -s -o "$COMPOSE_FILE" https://deploy.getlago.com/docker-compose.light.yml
        curl -s -o .env https://deploy.getlago.com/.env.light.example
        if [ $? -eq 0 ]; then
            echo "${GREEN}✅ Successfully downloaded Light deployment files${NORMAL}"
        else
            echo "${RED}❌ Failed to download Light deployment files${NORMAL}"
            exit 1

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

run_compose up -d in the Local branch does not enable the all profile. In docker-compose.local.yml, core services like db/redis/rsa-keys are under the all (and related) profiles, so running without --profile all will skip them and the stack will not come up correctly. Update the Local execution path to include the appropriate profile (e.g., --profile all) or set profile="all" for Local as well.

[Copilot]

check_domain_dns only checks an IPv4 A record (dig ... A) but the docs and many VPS setups rely on IPv6 (AAAA) as well. Consider checking for both A and AAAA (and adjusting the message) so valid IPv6-only domains don't fail the preflight check.

[Copilot]

The prerequisites state that ports 80 and 443 must be reachable for Light/Production, but the provided Traefik configuration in these compose files uses the TLS-ALPN challenge on :443 and does not expose an :80 entrypoint. Update the docs to reflect the actual port requirements (or update the compose files to also bind 80 if that's intended).

[Copilot]

The checklist says to open inbound ports 80 and 443, but the current Light/Production Traefik setup only binds 443 (TLS challenge). Either remove 80 from the checklist or explain when/why 80 is needed (e.g., if adding an HTTP->HTTPS redirect entrypoint).

[Copilot]

The “Apply .env changes safely” commands use docker compose down/up without specifying the compose file. Earlier in this doc the files are saved as docker-compose.light.yml / docker-compose.production.yml, so these commands won’t affect the running stack unless the user renamed the file to docker-compose.yml. Update the example to include -f <compose-file> (or instruct users to use the default filename).