Repository navigation
Deployment
Laravex is a pure Elixir/OTP application with a minimal dependency footprint. Its runtime requires Elixir and, depending on which drivers you configure, one or more CLI tools (sqlite3, psql, mysql) or external services (Redis over TCP, an SMTP relay, an S3-compatible store). There is no extra Hex package to compile in production.
For the full driver support matrix, see Limitations. For the official production deployment checklist, refer to docs/DEPLOY.md in the repository.
| Requirement | Minimum |
|---|---|
| Elixir | ~> 1.17 |
| Erlang/OTP | Compatible with the installed Elixir version |
| Operating system | Linux, macOS (Windows is untested) |
Optional CLI tools — only needed when the matching driver is configured:
| CLI | Required when |
|---|---|
sqlite3 |
DB_CONNECTION=sqlite (the default) |
psql |
DB_CONNECTION=pgsql or postgres
|
mysql |
DB_CONNECTION=mysql or mariadb
|
redis-server (or remote) |
CACHE_STORE=redis, SESSION_DRIVER=redis, or QUEUE_CONNECTION=redis
|
mix deps.get --only prodLaravex's mix.exs declares a single Hex dependency — dialyxir — which is scoped to :dev and :test only. The production build has no Hex runtime dependencies.
Copy .env.example to .env and set your production values:
cp .env.example .envThe critical variables for a production deployment are:
APP_ENV=production
APP_KEY=base64:... # 32-byte base64 key; keep secret
APP_URL=https://example.com
APP_DEBUG=false
# --- Database ---
DB_CONNECTION=sqlite # or pgsql / mysql / mariadb
DB_DATABASE=/var/www/myapp/database/database.sqlite
# DB_HOST=127.0.0.1 # for pgsql/mysql
# DB_PORT=5432
# DB_USERNAME=laravex
# DB_PASSWORD=secret
# --- Cache ---
CACHE_STORE=database # or file | redis | array
# --- Session ---
SESSION_DRIVER=database # or file | redis
# --- Queue ---
QUEUE_CONNECTION=database # or redis | sync | deferred
# --- Mail ---
MAIL_MAILER=smtp # or log | array
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=postmaster@example.com
MAIL_PASSWORD=secret
# --- Redis (when any driver uses redis) ---
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
# --- S3 (when FILESYSTEM_DISK=s3) ---
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=my-bucket
Generate a fresh APP_KEY:
./artisan key:generateLaravex loads .env at boot via Laravex.Env.load!/1. Variables set in the system environment take precedence over .env file values, so you can pass secrets via your process manager or container runtime without modifying the file on disk.
Compile the application in :prod mode:
MIX_ENV=prod mix compileBecause start_permanent: Mix.env() == :prod is set in mix.exs, the BEAM VM will shut down if the top-level supervisor crashes — appropriate for a process manager that handles restarts.
Before starting the server, run any pending database migrations:
MIX_ENV=prod ./artisan migrateThis creates the database (or connects to MySQL/PostgreSQL) if it does not already exist and applies all unapplied migration files in database/migrations/.
MIX_ENV=prod mix run --no-haltThe server listens on port 8000 by default in production (configured in config/prod.exs). Override with an environment variable if your platform expects a different port:
# config/prod.exs
config :laravex, http_port: 8000For long-lived production deployments, run Laravex under a process manager such as systemd or supervisord:
# /etc/systemd/system/myapp.service
[Unit]
Description=Laravex Application
After=network.target
[Service]
Type=simple
User=www
WorkingDirectory=/var/www/myapp
ExecStart=/usr/bin/mix run --no-halt
Restart=on-failure
Environment=MIX_ENV=prod
EnvironmentFile=/var/www/myapp/.env
[Install]
WantedBy=multi-user.targetsystemctl enable myapp
systemctl start myappLaravex registers two built-in health routes:
| Path | Description |
|---|---|
/up |
Configured via Application.with_routing(health: "/up") in bootstrap/app.ex; returns 200 OK
|
/health |
Built-in; returns a JSON health check payload |
Use either endpoint with your load balancer or container orchestrator.
For serving static assets and proxying HTTP requests to Laravex, place Nginx (or Caddy) in front:
server {
listen 80;
server_name example.com;
root /var/www/myapp/public;
location /storage {
alias /var/www/myapp/storage/app/public;
try_files $uri =404;
}
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Enable the storage symlink so that files in storage/app/public are accessible via /storage:
./artisan storage:link./artisan down # enable maintenance mode (503)
./artisan up # disable maintenance modeRequests received while in maintenance mode are rejected with a 503 response by the PreventRequestsDuringMaintenance middleware.
-
Route cache — cache the compiled route table to skip parsing on every boot:
./artisan route:cache
Clear with
./artisan route:clear. -
Event cache — pre-compile event-to-listener mappings:
./artisan event:cache
Clear with
./artisan event:clear. -
SQLite performance — for high-read workloads, consider setting
journal_mode=WALinconfig/database.exsand ensuring the database file lives on fast local storage. -
PostgreSQL/MySQL connection overhead — the CLI-based adapter spawns a new process for each query. For high-throughput workloads, place a connection pooler (e.g. PgBouncer, ProxySQL) between the app server and the database. See Limitations for details.
Laravex's drivers ship zero Hex runtime dependencies. The trade-offs are:
| Subsystem | Production-ready options |
|---|---|
| Database | SQLite (single-node), PostgreSQL or MySQL via CLI |
| Cache |
database, file, or redis
|
| Session |
database, file, or redis
|
| Queue |
database or redis
|
smtp (plain TCP/TLS) |
|
| Storage |
local or s3 (SigV4-signed :httpc) |
| Broadcasting |
pubsub (in-process only) |
Before deploying, review Limitations to confirm your chosen drivers are implemented and to understand the remaining constraints of each.
Laravex — Laravel-faithful application skeleton & runtime for Elixir.
GitHub
·
Docs
·
Limitations
·
Laravel Docs
Not affiliated with Laravel LLC or the Elixir core team. Built to feel like Laravel on the BEAM.
- Home
- Installation
- Configuration
- Directory-Structure
- Request-Lifecycle
- Service-Container
- Service-Providers
- Deployment
- Routing
- Middleware
- CSRF-Protection
- Controllers
- Requests
- Responses
- Views
- Blade-Templates
- Asset-Bundling
- Session
- Validation
- Error-Handling
- Logging
- Artisan-Console
- Broadcasting
- Cache
- Collections
- Events
- File-Storage
- Helpers
- HTTP-Client
- Localization
- Notifications
- Pipeline
- Queues
- Rate-Limiting
- Strings
- Task-Scheduling