Self-Hosting Guide

1) What you need before you start

• A Linux VPS (Ubuntu/Debian recommended) with root or sudo access
• A domain name pointed at your VPS
• SMTP mailbox credentials for your sender address (example: noreply@yourdomain.com)
• An Anthropic Console account and API key
• A Twilio account, SMS-capable number, and A2P 10DLC registration for outbound US texting

2) Clone and deploy Romp CRM on your VPS

2.1 Install platform dependencies

Install Elixir (compatible with the version in .tool-versions or mix.exs in the repo), Erlang/OTP, Node.js, Git, SQLite client libraries, and nginx on your VPS (package names vary by distro).

2.2 Clone the app

git clone https://github.com/151henry151/romp-crm.git
cd romp-crm

2.3 Create production env file

cp deploy/romp-crm.env.example .env.production
chmod 600 .env.production

2.4 Build release

MIX_ENV=prod mix deps.get
MIX_ENV=prod mix assets.deploy
MIX_ENV=prod mix release

2.5 SQLite data directory

Create the directory for your SQLite file before the first start (match your DATABASE_PATH):

mkdir -p /home/youruser/romp-crm/data

2.6 Install systemd unit

The example unit uses User=henry, WorkingDirectory=/home/henry/romp-crm, and EnvironmentFile=/home/henry/romp-crm/.env.production. Edit those paths and the Unix user to match your server, then install:

sudo install -m 644 deploy/romp-crm.service /etc/systemd/system/romp-crm.service
sudo systemctl daemon-reload
sudo systemctl enable --now romp-crm
sudo systemctl status romp-crm

Systemd reads variables from EnvironmentFile (you do not need export lines in that file). After editing .env.production, restart: sudo systemctl restart romp-crm.

3) Configure your Romp CRM environment

Production loads .env.production at runtime; see config/runtime.exs in the repo for the full list of variables. At minimum, set:

MIX_ENV=prod
PHX_SERVER=true
PHX_HOST=yourdomain.com
PORT=40175
SECRET_KEY_BASE=...generated...
DATABASE_PATH=/home/youruser/romp-crm/data/romp_crm.db

MAIL_FROM_NAME="Romp CRM"
MAIL_FROM_ADDRESS=noreply@yourdomain.com
SMTP_HOST=your.smtp.host
SMTP_PORT=587
SMTP_TLS=always
SMTP_USERNAME=noreply@yourdomain.com
SMTP_PASSWORD="your-mail-password"

TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_MESSAGING_FROM=+1XXXXXXXXXX
TWILIO_WEBHOOK_PUBLIC_URL=https://yourdomain.com/romp-crm/webhooks/twilio/sms
TWILIO_SMS_REPLIES_ENABLED=true

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-20250514

ENFORCE_REGISTRATION_ALLOWLIST=false

3.1 Subscription paywall (usually off for self-host)

Leave SUBSCRIPTION_PAYWALL_ENABLED unset or set it to false so new accounts are active without PayPal (typical self-host). If you set SUBSCRIPTION_PAYWALL_ENABLED=true, you must supply all PayPal billing variables (client id/secret, plan ids, webhook id, etc.) as documented in the repo’s deploy/README.md and the mix paypal.provision flow.

3.2 Public URL path (/romp-crm)

The default production build expects the app under /romp-crm on your public host (see config/prod.exs :path_prefix). Nginx must strip that prefix when proxying to Phoenix. To serve at the site root (/) instead, change :path_prefix and the endpoint url: [path: …] to match, then run a new mix release.

3.3 Optional

• Admin dashboard — comma-separated ADMIN_EMAILS (override the built-in default list in production).
• Twilio voice — TWILIO_VOICE_WEBHOOK_PUBLIC_URL and TWILIO_VOICE_FORWARD_TO if you use the voice webhook.
• Transactional email branding — EMAIL_LOGO_URL and EMAIL_BRAND_BASE_URL.
• CSRF / LiveView origins — PHX_CHECK_ORIGINS if you expose multiple public hostnames.

4) Set up Anthropic and get your API key

1. Create/login at console.anthropic.com.
2. Set up billing for production use.
3. Create an API key from API Keys section.
4. Put it into ANTHROPIC_API_KEY in .env.production.
5. Restart Romp CRM after updating env.

sudo systemctl restart romp-crm

5) Set up Twilio (including A2P 10DLC for outbound)

5.1 Create Twilio project and buy an SMS-capable US number

1. Create/login at console.twilio.com.
2. Buy a US number with SMS capability.
3. Copy Account SID and Auth Token.

5.2 Register for A2P 10DLC (required for reliable US outbound texting)

1. In Twilio Console, go to Messaging -> Regulatory Compliance -> A2P 10DLC.
2. Create your Brand (business identity info).
3. Create Campaign Use Case matching your SMS purpose (customer updates, transactional notifications).
4. Attach your phone number to that campaign.

5.3 Configure inbound webhook for your number

Set your number's “A message comes in” webhook to:

https://yourdomain.com/romp-crm/webhooks/twilio/sms

Method: POST.

5.4 Optional: configure via provided Mix task

Run from the app clone with the same MIX_ENV you use to build the release (usually prod):

set -a && source .env.production && set +a
MIX_ENV=prod mix twilio.configure_sms --phone +1XXXXXXXXXX --sms-url "$TWILIO_WEBHOOK_PUBLIC_URL"

5.5 If using Twilio Messaging Service

Enable “defer inbound to sender webhook” behavior:

set -a && source .env.production && set +a
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx MIX_ENV=prod mix twilio.messaging_service_inbound

6) Nginx and HTTPS (Let’s Encrypt)

1. Proxy /romp-crm/ to your release port (default 40175) and strip prefix with trailing slash in proxy_pass.
2. Expose /.well-known/acme-challenge/ for webroot cert issuance.
3. Issue cert for apex + www with certbot.
4. Enable HTTP -> HTTPS redirect and reload nginx.

See deployment files in repo for reference:

• deploy/README.md
• deploy/nginx-location-romp-crm.conf

7) Verification checklist