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).
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
🌸 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
- .env: asks before setting
DEBUG=False,APP_ENV=production,HOST=127.0.0.1,PORT,SERVICE_NAMEandAPP_URL(https when Certbot is used). The previous file is kept as.env.bak.SECRET_KEYis never rotated by the assistant (it would sign out every user): a weak key only prints a warning; runlila secret-keyyourself before the first deploy. - systemd: installs
<service>.service(and<service>-worker.servicewhenCACHE_DRIVER=redisand you ask for it), enables and restarts it. - Nginx: offers to install Nginx with apt-get, writes the site to
sites-available+ a symlink insites-enabled(orconf.don RHEL-like systems), can disable the default site, runsnginx -tand disables the new site again if the test fails. - HTTPS: offers to install
certbot+python3-certbot-nginxand requests the certificate with an HTTP→HTTPS redirect. Your DNS must already point to the server. - Permissions: when needed it asks to run, in the same session,
chown -R user:useron the project (the service writes the SQLite database, logs, cache and uploads),chmod o+xon the parent folders Nginx cannot traverse pluschmod -R o+rX public(projects inside a private/home/user), andchown user .env && chmod 600 .env(also.env.bak). Declined fixes are printed as warnings. - Check: finally it calls the app on its internal port.
- Without root it only generates
deploy/and prints the commands.--dry-rundoes the same as root;--yesaccepts every default (requiresAPP_URLwith a real domain).
The rest of this page explains each step for a manual setup.
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
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install lila-framework
2. Create a Start Script
#!/bin/bash
set -e
cd /path/to/your/project
source venv/bin/activate
exec lila run -w 2
3. Create a systemd 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
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.
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.
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.
- Create a `.bat` or `.ps1` script to start your application.
- Open Task Scheduler and create a new task that runs at system startup.
- 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().