Skip to main content
MeepaChat is configured via a YAML file and environment variables. Environment variables always take precedence over the config file.

​
Config File Location

MeepaChat searches for a config file in this order:
  1. $MEEPA_CONFIG_PATH — if set, only this path is checked
  2. ~/.meepachat/config.yaml — primary location (written by meepachat init)
  3. /etc/meepa/config.yaml — system-wide location
meepachat init writes the config to ~/.meepachat/config.yaml automatically.

​
Precedence

environment variables  (highest)
    ↓
~/.meepachat/config.yaml
    ↓
built-in defaults      (lowest)

​
Server

​
PORT
integer
default:"8091"
HTTP port the server listens on. Can also be set via meepachat start --port N.
​
BIND
string
default:"(all interfaces)"
Network address to bind to. Can also be set via meepachat start --bind ADDR.
​
BASE_URL
string
Public URL of the server (e.g. https://chat.example.com). Required for invite links and email links to work correctly. Also controls whether session cookies are set with the Secure flag — set this to an https:// URL in production.
​
LOG_FORMAT
string
default:"text"
Log output format. text for human-readable output, json for structured logs.
Config file equivalent: 
port: 8091
bind: ""
domain: https://chat.example.com

​
Database

​
DATABASE_URL
string
PostgreSQL connection string. MeepaChat runs migrations automatically on startup.
​
REDIS_URL
string
default:"redis://redis:6379/0"
Redis connection string. Used for WebSocket pub/sub when running multiple server instances. Optional — omit to run without Redis (single instance only).
Config file equivalent: 
database_url: postgres://user:pass@localhost:5432/meepachat?sslmode=disable
redis_url: redis://localhost:6379/0

​
Authentication

​
BETTER_AUTH_URL
string
URL of the auth service. Set by meepachat init.
​
BETTER_AUTH_SECRET
string
Shared secret for the auth service. Must match the value configured in the auth sidecar.
​
OPEN_REGISTRATION
boolean
default:"true"
When false, new users must have a valid invite link to register. The first user is always exempt and becomes admin.
​
REQUIRE_EMAIL_VERIFICATION
boolean
default:"false"
When true, users must verify their email address before they can log in. Requires SMTP to be configured.
Config file equivalent: 
open_registration: false

better_auth:
  url: http://localhost:8093
  secret: your-secret-here

​
File Storage

MeepaChat stores uploads in S3-compatible storage. If no S3 endpoint is configured, files are stored on the local filesystem.
​
S3_ENDPOINT
string
S3-compatible endpoint URL. Omit the https:// scheme — set S3_USE_SSL=true separately.Examples: localhost:9010 (MinIO), your-account.r2.cloudflarestorage.com (Cloudflare R2), s3.amazonaws.com (AWS S3).
​
S3_ACCESS_KEY
string
S3 access key ID.
​
S3_SECRET_KEY
string
S3 secret access key.
​
S3_BUCKET
string
default:"meepachat"
S3 bucket name. The bucket must already exist.
​
S3_REGION
string
S3 region. Required for AWS S3. Optional for MinIO and Cloudflare R2.
​
S3_USE_SSL
boolean
default:"false"
Enable TLS when connecting to the S3 endpoint. Set to true for any public S3 service.
​
UPLOAD_DIR
string
default:"/data/uploads"
Local directory for file uploads when S3 is not configured. Also used as a temporary staging area when S3 is enabled.
​
MAX_UPLOAD_SIZE
integer
default:"20971520"
Maximum file upload size in bytes. Default is 20 MB (20 × 1024 × 1024).
Config file equivalent: 
upload_dir: /data/uploads
max_upload_size: 20971520

storage:
  endpoint: your-account.r2.cloudflarestorage.com
  access_key: your-access-key
  secret_key: your-secret-key
  bucket: meepachat
  region: auto
  use_ssl: true

​
MinIO (default)

meepachat init starts a local MinIO instance. No additional configuration needed for local deployments.

​
Cloudflare R2

storage:
  endpoint: <account-id>.r2.cloudflarestorage.com
  access_key: <r2-access-key-id>
  secret_key: <r2-secret-access-key>
  bucket: meepachat
  region: auto
  use_ssl: true

​
AWS S3

storage:
  endpoint: s3.amazonaws.com
  access_key: <aws-access-key-id>
  secret_key: <aws-secret-access-key>
  bucket: meepachat
  region: us-east-1
  use_ssl: true
Legacy MINIO_* environment variables (MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, MINIO_USE_SSL) are still accepted as fallbacks when the corresponding S3_* variable is not set.

​
SMTP / Email

Email is used for invite links and email verification. Optional unless REQUIRE_EMAIL_VERIFICATION=true.
​
SMTP_HOST
string
SMTP server hostname (e.g. smtp.mailgun.org, smtp.gmail.com).
​
SMTP_PORT
integer
default:"587"
SMTP port. 587 for STARTTLS (recommended), 465 for TLS, 25 for unencrypted.
​
SMTP_USER
string
SMTP username.
​
SMTP_PASS
string
SMTP password.
​
SMTP_FROM
string
From address for outgoing email (e.g. chat@example.com).
Config file equivalent: 
smtp:
  host: smtp.mailgun.org
  port: 587
  user: postmaster@mg.example.com
  pass: your-smtp-password
  from: chat@example.com

​
Push Notifications

​
Web Push (VAPID)

Browser push notifications use VAPID keys. Generate them once and store them permanently — changing keys will break existing browser subscriptions.
​
VAPID_PUBLIC_KEY
string
Base64url-encoded ECDSA P-256 public key.
​
VAPID_PRIVATE_KEY
string
Base64url-encoded ECDSA P-256 private key.
​
VAPID_SUBJECT
string
Contact URL or mailto: address identifying the push server (e.g. mailto:admin@example.com).
Generate VAPID keys: 
npx web-push generate-vapid-keys
Config file equivalent: 
push:
  vapid_public_key: BxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA
  vapid_private_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  vapid_subject: mailto:admin@example.com

​
FCM (Firebase Cloud Messaging)

Required for push notifications on iOS and Android mobile apps.
​
FCM_CREDENTIALS_FILE
string
Path to a Firebase service account JSON file. Download from Firebase Console → Project Settings → Service accounts.
Config file equivalent: 
push:
  fcm_credentials_file: /etc/meepachat/firebase-credentials.json

​
Sessions

​
SESSION_TTL
duration
default:"720h"
How long login sessions remain valid. Accepts Go duration strings: 720h (30 days), 168h (7 days), 24h (1 day).
Config file equivalent: 
session_ttl: 720h

​
CORS

​
CORS_ORIGINS
string
Comma-separated list of allowed CORS origins. When not set, only same-origin requests are permitted.Example: https://chat.example.com,https://app.example.com
​
TIKA_URL
string
URL of an Apache Tika server for full-text extraction from uploaded files (PDF, Office docs, etc.). Optional — omit to skip content indexing of attachments.Example: http://localhost:9998
Config file equivalent: 
tika_url: http://localhost:9998

​
Auto-Update

​
MEEPA_AUTO_UPDATE
boolean
default:"false"
When true, the server checks for updates every 6 hours and restarts automatically if a new version is available. Connected clients receive an update_restarting WebSocket event before the restart.
Config file equivalent: 
auto_update: true

​
Complete Config File Example

# ~/.meepachat/config.yaml

setup_complete: true
domain: https://chat.example.com
port: 8091

database_url: postgres://meepachat:secret@localhost:5432/meepachat?sslmode=disable
redis_url: redis://localhost:6379/0

open_registration: false
session_ttl: 720h

better_auth:
  url: http://localhost:8093
  secret: your-better-auth-secret

storage:
  endpoint: your-account.r2.cloudflarestorage.com
  access_key: your-access-key
  secret_key: your-secret-key
  bucket: meepachat
  region: auto
  use_ssl: true

smtp:
  host: smtp.mailgun.org
  port: 587
  user: postmaster@mg.example.com
  pass: your-smtp-password
  from: chat@example.com

push:
  vapid_public_key: BxxxxA
  vapid_private_key: xxxxx
  vapid_subject: mailto:admin@example.com
  fcm_credentials_file: /etc/meepachat/firebase-credentials.json

auto_update: true