Skip to content

Deployment

David Ciulla edited this page Nov 7, 2026 · 2 revisions

Deployment

Introduction

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.


Server Requirements

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

Installing Dependencies

mix deps.get --only prod

Laravex'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.


Environment Configuration

Copy .env.example to .env and set your production values:

cp .env.example .env

The 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:generate

Laravex 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.


Building for Production

Compile the application in :prod mode:

MIX_ENV=prod mix compile

Because 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.


Running Migrations

Before starting the server, run any pending database migrations:

MIX_ENV=prod ./artisan migrate

This creates the database (or connects to MySQL/PostgreSQL) if it does not already exist and applies all unapplied migration files in database/migrations/.


Starting the Server

MIX_ENV=prod mix run --no-halt

The 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: 8000

Using a Process Manager

For 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.target
systemctl enable myapp
systemctl start myapp

Health Check

Laravex 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.


Putting Files Behind a Web Server (Nginx)

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

Maintenance Mode

./artisan down          # enable maintenance mode (503)
./artisan up            # disable maintenance mode

Requests received while in maintenance mode are rejected with a 503 response by the PreventRequestsDuringMaintenance middleware.


Optimisation Tips

  • 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=WAL in config/database.exs and 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.


Driver Notes

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
Mail 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.

Clone this wiki locally