Deployment to Production

Guided setup: sudo lila deploy setup (Linux)

The quickest way to put a project online on an Ubuntu/Debian VPS. Run it from the project root (where .env lives) after creating the virtual environment. It asks one question at a time, like lila init: press Enter to accept the value read from .env, answer S/N (or Y/N) or type a new value. Messages follow LANG_DEFAULT (English or Spanish).

Terminal
cd /srv/my-shop
python -m venv venv && source venv/bin/activate
pip install lila-framework
lila migrate

# sudo does not keep the venv PATH: pass the full path to lila
sudo "$(which lila)" deploy setup
Example session
🌸 Lila production setup (Linux)

? DEBUG is True in .env. Set DEBUG=False for production? [Y/n]
? HOST is 0.0.0.0. Bind the app to 127.0.0.1 (only Nginx can reach it)? [Y/n]
  ⚠️  SECRET_KEY is empty, short or a placeholder. It is not changed here (...) run `lila secret-key`
? Domain (without http://) [shop.example.com]
? Also serve www.shop.example.com? [Y/n]
? Internal port for the app [3002]
? Use the service name from .env (my-shop)? [Y/n]
? Linux user that runs the app [deploy]
? Number of workers [1]
? Install the Nginx site? [Y/n]
? Request a free HTTPS certificate with Certbot (Let's Encrypt)? [Y/n]
? E-mail for Let's Encrypt notices [admin@shop.example.com]
? /srv/my-shop is owned by 'root' but the service runs as 'deploy' (...). Run `chown -R deploy:deploy /srv/my-shop` now? [Y/n]
? .env is readable by other users (it contains secrets). Restrict it to 'deploy' (`chown deploy .env && chmod 600 .env`) now? [Y/n]

Summary
  • Domain   shop.example.com + www.shop.example.com
  • URL      https://shop.example.com
  • Service  my-shop.service
  ...
? Apply these changes? [Y/n]

  $ chown -R deploy:deploy /srv/my-shop
  $ chown deploy:deploy /srv/my-shop/.env
  $ chmod 600 /srv/my-shop/.env
  $ cp deploy/my-shop.service /etc/systemd/system/my-shop.service
  $ systemctl daemon-reload
  $ systemctl enable --now my-shop.service
  $ cp deploy/shop.example.com.nginx.conf /etc/nginx/sites-available/shop.example.com.conf
  $ ln -sf /etc/nginx/sites-available/shop.example.com.conf /etc/nginx/sites-enabled/shop.example.com.conf
  $ nginx -t
  $ systemctl reload nginx
  $ certbot --nginx --non-interactive --agree-tos --redirect -m admin@shop.example.com -d shop.example.com -d www.shop.example.com
✅ The app answers on http://127.0.0.1:3002/ (HTTP 200).
🚀 Done! Your site: https://shop.example.com

The rest of this page explains each step for a manual setup.

Before deploying run lila css build (compiled Tailwind instead of the 270 KB runtime), lila optimize and lila doctor. See Performance, Health & Metrics and Tasks (lila deploy --with-worker now works with the SQLite queue, no Redis needed).

Linux Server (with systemd)

To deploy your Lila application on a Linux server, it's recommended to use a virtual environment and a systemd service to manage the process.

1. Create a Virtual Environment

Terminal

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install lila-framework
          

2. Create a Start Script

start_lila.sh

#!/bin/bash
set -e
cd /path/to/your/project
source venv/bin/activate
exec lila run -w 2
                        

3. Create a systemd Service

/etc/systemd/system/lila.service

[Unit]
Description=Lila Framework Service
After=network.target

[Service]
User=your_user
Group=your_group
WorkingDirectory=/path/to/your/project
ExecStart=/path/to/your/project/start_lila.sh
Restart=always
RestartSec=10
Environment=PATH=/path/to/your/project/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
Environment=PYTHONPATH=/path/to/your/project

[Install]
WantedBy=multi-user.target
                        

4. Enable and Start the Service

Termial

sudo systemctl daemon-reload
sudo systemctl enable lila.service
sudo systemctl start lila.service
chmod +x /path/to/your/project/start_lila.sh

                        

5. Disable Debug Mode

In your `.env` file, make sure to set `DEBUG=False` for production.

.env
 
DEBUG=False
                        

Important error handling details: unhandled exceptions are logged by Logger.error() (traceback included) into app/logs/YYYY-MM-DD/error.log. The client always receives a generic 500: JSON {"success": false, "message": "Internal server error"} for /api/ or Accept: application/json requests, a minimal HTML page otherwise. A template render error additionally shows the traceback panel when debug mode is on.

When you deploy to production and set DEBUG=False, Lila hides tracebacks and returns a generic 500 page (JSON {"success": false, "message": "Internal server error"} for API clients). 404 responses use your project's resources/html/404.jinja when it exists, otherwise the bundled lila/404 template.

6. Configure Nginx (Optional)

The fastest path is lila deploy --domain your-domain.com --port 3002. It writes a ready-to-copy systemd unit plus an Nginx config that proxies the app and serves Lila's real static paths (/public/, /js/, /img/, /swagger/, /uploads/) directly, with WebSocket support and gzip_static on for pre-compressed assets. /js/lila-client.js and /js/ws.js are proxied to the app so the version from the installed package is always served. The manual example below is equivalent.

/etc/nginx/sites-available/your-domain.com

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com www.your-domain.com;

    # Redirect all HTTP traffic to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name your-domain.com www.your-domain.com;

    # SSL Certificates
    ssl_certificate /etc/nginx/ssl/your-domain.com/your-domain.com.crt;
    ssl_certificate_key /etc/nginx/ssl/your-domain.com/your-domain.com.key;

    # Lila Framework Reverse Proxy in port 3002
    location / {
        proxy_pass http://127.0.0.1:3002;
        proxy_http_version 1.1;
        
        # WebSockets and Connection Headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeouts for long-running connections
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}
          

Windows Server

On Windows, you can use the Task Scheduler to run your application at startup.

  1. Create a `.bat` or `.ps1` script to start your application.
  2. Open Task Scheduler and create a new task that runs at system startup.
  3. Set the action to run your script.

Zero-Infrastructure VPS Deployment

Lila is intentionally zero-infrastructure by default: asynchronous SQLite in WAL mode (PRAGMA journal_mode=WAL;) and an in-memory LRU cache. Measured on Python 3.14: import lila is about 19 MB RSS (lazy imports, no SQLAlchemy until models are used) and a full App instance is about 42 MB. No database container, daemon or Docker stack is required for a typical 1–2 worker app.

⚡ SQLite async WAL mode

Each SQLite connection applies journal_mode=WAL, synchronous=NORMAL, busy_timeout=5000, a ~4 MB page cache (cache_size=-4000) and foreign keys. Readers do not block writers, but SQLite still allows a single writer at a time — benchmark your workload instead of assuming linear scaling.

Backups

Use lila backup --max-backups 14 for a consistent online SQLite backup; it uses SQLite's native backup API and does not stop the server. Schedule it with cron/Task Scheduler and keep copies outside the project directory.

1. Production ASGI Workers

The simplest production command is lila run -w 2, which reads HOST/PORT from .env. With more than one worker, the in-memory cache, rate-limit counters and server-side session payloads are per worker — Lila prints a warning and you should switch to Redis for shared state:

# Recommended: one process per app (SQLite + memory cache)
lila run -w 1

# Multi-worker: shared cache/sessions needed
#   .env -> CACHE_DRIVER="redis"
lila run -w 4

# Equivalent raw Uvicorn command (run from the project root)
uvicorn main:app --host 127.0.0.1 --port 3002 --workers 4

2. Production Environment Variables Checklist

Verify your .env settings before starting the service:

# Essential production configuration
DEBUG=False
PORT=3002
HOST=127.0.0.1
APP_URL=https://your-domain.com

# Generate a strong key first: lila secret-key
# (An empty/placeholder value makes Lila generate .lila_secret and warn.)
SECRET_KEY="paste-the-output-of-lila-secret-key"

# Zero-infra default cache (per process)
CACHE_DRIVER="memory"

# Multi-worker / multi-node: shared state
# CACHE_DRIVER="redis"
# REDIS_HOST="127.0.0.1"
# REDIS_PORT=6379

3. Background Worker Process (Optional)

If your application offloads heavy jobs (AI calls, image processing, bulk emails), launch the Lila worker as a secondary systemd unit. It consumes JSON tasks from Redis and requires a reachable Redis server:

# Run the Lila background task consumer (same forms: lila worker start / lila-worker)
lila worker

4. Process Inspection & Journal Logs

# Real-time service logs
sudo journalctl -u lila.service -f

# Check systemd status
sudo systemctl status lila.service

# Restart service after deployment
sudo systemctl restart lila.service

5. Multi-Project VPS Hosting with Nginx

Each Lila App uses roughly 42 MB RSS, so several small projects fit on a $5 VPS by binding each one to a different internal port:

# Project A (.env): PORT=3001 -> proxy_pass http://127.0.0.1:3001;
# Project B (.env): PORT=3002 -> proxy_pass http://127.0.0.1:3002;
# Project C (.env): PORT=3003 -> proxy_pass http://127.0.0.1:3003;

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Proxy headers: lila run enables --proxy-headers by default and trusts X-Forwarded-* only from --forwarded-allow-ips 127.0.0.1 (a local Nginx), so client IPs used by rate limits are correct. If the proxy runs on another host, pass its IP. Keep APP_URL="https://..." so cookies are marked secure, and keep the WebSocket upgrade headers shown above when using router.ws_hub().

Production Configurator

Production Configurator

Fill in your server details to automatically update the snippets above.