Skip to content

Configuration reference

Every setting lives in the environment. Copy .env.example to .env for local development; in production systemd supplies an EnvironmentFile. Process environment always wins over .env (precedence: --env-file → APP_ENV_FILE → .env → code defaults). ims config:show prints the effective values with secrets masked.

Commented rows are optional: the code default applies until you set them.

App

Variable Example Notes
APP_ENV local
APP_NAME ims-go-api
APP_DEBUG true
APP_URL http://localhost:8080
APP_LISTEN_ADDR :8080
APP_TIMEZONE Asia/Dhaka
APP_LOCALE en
APP_FALLBACK_LOCALE en
APP_SUPPORTED_LOCALES en,bn
APP_LOG_LEVEL info
APP_DATA_DIR ./var
APP_STORAGE_DIR ./var/storage
APP_CACHE_DIR ./var/cache
APP_LOG_DIR — Optional. empty → stdout (journald in production)
APP_ENV_FILE ./.env Optional.

HTTP

Variable Example Notes
HTTP_READ_TIMEOUT 15s
HTTP_WRITE_TIMEOUT 90s
HTTP_IDLE_TIMEOUT 60s
HTTP_SHUTDOWN_TIMEOUT 30s
HTTP_REQUEST_TIMEOUT 60s
HTTP_MAX_REQUEST_BODY_BYTES 10485760
HTTP_STRICT_JSON_FIELDS true
HTTP_TRUSTED_PROXIES 127.0.0.1,10.0.0.0/8 Optional. honour X-Forwarded-For only from these peers
RATE_LIMIT_PER_MINUTE 1000

Database

Variable Example Notes
DATABASE_DRIVER pgsql pgsql (v1 is PostgreSQL-only)
DATABASE_DSN postgres://postgres:postgres@127.0.0.1:5432/ims_go_api?sslmode=disable
DATABASE_MAX_CONNS 20
DATABASE_MIN_CONNS 2
DATABASE_CONN_TIMEOUT 5s
DATABASE_STATEMENT_TIMEOUT 5m server-side query backstop (0 = off; raise for huge migrations)
DATABASE_IDLE_IN_TX_TIMEOUT 1m kills sessions idling inside an open transaction
DATABASE_CONNECTIONS primary,analytics Optional. Named extra connections (optional):
DATABASE_ANALYTICS_DRIVER pgsql Optional.
DATABASE_ANALYTICS_DSN — Optional.
DATABASE_TEST_DSN postgres://postgres:postgres@127.0.0.1:5432/ims_go_api_test?sslmode=disable Optional. Integration tests (dedicated throwaway database):

Cache

Variable Example Notes
CACHE_DRIVER memory memory | file | redis | database
CACHE_PREFIX ims-
CACHE_FILE_DIR ./var/cache Optional.
REDIS_ADDR 127.0.0.1:6379
REDIS_PASSWORD —
REDIS_DB 0
REDIS_CACHE_DB 1

Queue

Variable Example Notes
QUEUE_DRIVER river river | sync
QUEUE_CRITICAL_TRIES 3
QUEUE_CRITICAL_TIMEOUT 60
QUEUE_DEFAULT_TRIES 5
QUEUE_DEFAULT_TIMEOUT 120
QUEUE_HEAVY_TRIES 1
QUEUE_HEAVY_TIMEOUT 1800
QUEUE_WORKER_CONCURRENCY 10

Scheduler

Variable Example Notes
SCHEDULE_TIMEZONE Asia/Dhaka

Auth

Variable Example Notes
AUTH_TOKEN_EXPIRATION 1440 minutes; 0 = never (refused in production)
AUTH_LOGIN_MAX_ATTEMPTS 5
AUTH_LOGIN_DECAY_MINUTES 1
AUTH_OTP_ENABLED false
AUTH_OTP_LENGTH 6
AUTH_OTP_EXPIRY_MINUTES 5
AUTH_DEFAULT_PASSWORD 123456
AUTH_CHECK_IS_ACTIVE true inactive users cannot log in
AUTH_CHECK_EMAIL_VERIFIED true unverified e-mail cannot log in
AUTH_CHECK_PHONE_VERIFIED false
AUTH_NEW_USERS_VERIFIED true false = admin-created/imported users must verify their e-mail
AUTH_PASSWORD_RESET_EXPIRY 60m
AUTH_EMAIL_VERIFY_EXPIRY 24h
AUTH_PASSWORD_RESET_URL https://app.example.com/reset-password?token={token}&email={email} Optional.
AUTH_EMAIL_VERIFY_URL https://app.example.com/verify-email?token={token} Optional.
BCRYPT_ROUNDS 12

Tenancy

Variable Example Notes
DEFAULT_TENANT_ID 1
DEFAULT_TENANT_NAME Main Tenant
DEFAULT_TENANT_CODE fad58de7366495db4650cfefac2fcd61
DEFAULT_TENANT_SLUG main-tenant
DEFAULT_TENANT_IS_ACTIVE true
DEFAULT_TENANT_EMAIL tenant@example.com
DEFAULT_TENANT_PHONE —
DEFAULT_BRANCH_ID 1
DEFAULT_BRANCH_NAME Default Branch

Billing

Variable Example Notes
BILLING_CURRENCY BDT
BKASH_BASE_URL / BKASH_APP_KEY= / BKASH_APP_SECRET= / BKASH_USERNAME= / BKASH_PASSWORD= Optional.
BKASH_CALLBACK_URL https://api.example.com/api/v1/billing/bkash/callback Optional.
NAGAD_BASE_URL / NAGAD_MERCHANT_ID= / NAGAD_MERCHANT_NUMBER= / NAGAD_PUBLIC_KEY= / NAGAD_PRIVATE_KEY= Optional.
BANK_TRANSFER_ACCOUNT_NAME / BANK_TRANSFER_ACCOUNT_NUMBER= / BANK_TRANSFER_BANK_NAME= / BANK_TRANSFER_BRANCH= Optional.

Mail

Variable Example Notes
MAIL_DRIVER log log | smtp
MAIL_HOST 127.0.0.1
MAIL_PORT 2525
MAIL_USERNAME —
MAIL_PASSWORD —
MAIL_ENCRYPTION — tls | starttls | "" (plain)
MAIL_FROM_ADDRESS hello@example.com
MAIL_FROM_NAME IMS Go API

Files & storage

Variable Example Notes
FILES_DISK public Disks work like Laravel’s config/filesystems.php: code only names a disk, so moving uploads to S3 / Cloudflare R2 / MinIO is a change of FILES_DISK. Built-in disks: private (local, served by the app), public (local, served at /storage) and s3 (when S3_* is set). Private disks never get direct URLs. any disk name: private | public | s3 | <STORAGE_DISKS name>
FILES_PUBLIC_DISK public Optional. where avatars go when FILES_DISK is private (must be public)
STORAGE_PUBLIC_DIR ./var/storage/public Optional.
STORAGE_PRIVATE_DIR ./var/storage/private Optional.
DATA_PROCESSING_DISK private any disk name
DATA_PROCESSING_BASE_PATH jobs
S3_ENDPOINT — Optional. The built-in “s3” disk (AWS S3 or any S3-compatible service): empty for AWS; set for R2/MinIO/Spaces/B2
S3_REGION — Optional. e.g. ap-southeast-1; “auto” for R2
S3_BUCKET — Optional.
S3_ACCESS_KEY — Optional.
S3_SECRET_KEY — Optional.
S3_PATH_STYLE false Optional. true for MinIO
S3_PUBLIC_URL — Optional. public base URL (CDN); empty → presigned GETs
S3_ROOT — Optional. optional key prefix inside the bucket
S3_VISIBILITY — Optional. public | private (default: public when S3_PUBLIC_URL is set)
STORAGE_DISKS r2,minio Optional. More disks: list names in STORAGE_DISKS and set STORAGE__* for each (DRIVER=s3|local, ENDPOINT, REGION, BUCKET, ACCESS_KEY, SECRET_KEY, PATH_STYLE, PUBLIC_URL, ROOT, VISIBILITY; local disks use ROOT and URL).
STORAGE_R2_ENDPOINT https://<account-id>.r2.cloudflarestorage.com Optional.
STORAGE_R2_BUCKET uploads Optional.
STORAGE_R2_ACCESS_KEY — Optional.
STORAGE_R2_SECRET_KEY — Optional.
STORAGE_R2_PUBLIC_URL https://files.example.com Optional. R2 custom domain → public disk
STORAGE_MINIO_ENDPOINT http://127.0.0.1:9000 Optional.
STORAGE_MINIO_BUCKET uploads Optional.
STORAGE_MINIO_ACCESS_KEY — Optional.
STORAGE_MINIO_SECRET_KEY — Optional.
STORAGE_MINIO_PATH_STYLE true Optional.
FILES_DISK r2 Optional.

Ops & security

Variable Example Notes
DOCS_ENABLED — Scalar API docs at /docs (default: on outside production)
METRICS_ENABLED false Prometheus metrics at /metrics
METRICS_TOKEN — Optional. bearer token for /metrics (unset = loopback only)
CACHE_MEMORY_MAX_ENTRIES 100000 Optional. memory cache driver bound
SECURITY_HEADERS_ENABLED true baseline hardening response headers
CORS_ALLOWED_ORIGINS — Optional. comma-separated; empty disables CORS entirely
CORS_ALLOWED_METHODS GET,POST,PATCH,PUT,DELETE,OPTIONS Optional.
CORS_ALLOWED_HEADERS Authorization,Content-Type,Accept,Accept-Language,X-Acting-Tenant,X-Acting-Branch,X-Tenant-Code,X-Branch-Id,X-Request-Id Optional.
CORS_MAX_AGE 600 Optional. seconds

Developer dashboard

Variable Example Notes
DEV_DASHBOARD_ENABLED — /dev SPA + /dev/api (default: on outside production)
DEV_DASHBOARD_CAPTURE http,sql,cache,queue,logs Optional.
DEV_DASHBOARD_SAMPLE_RATE 1.0 Optional. 0..1 telemetry sampling
DEV_DASHBOARD_RETENTION_DAYS 7 Optional.
DEV_DASHBOARD_AUDIT_RETENTION_DAYS 180 Optional. dashboard audit log (sign-ins and actions)
ACTIVITY_RETENTION_DAYS 365 Optional. activity log entries older than this are pruned (0 = keep)
DEV_DASHBOARD_MAX_BODY_BYTES 65536 Optional.
DEV_DASHBOARD_REDACT_KEYS — Optional. extra sensitive keys (comma-separated)
DEV_DASHBOARD_STORE database Optional.
BACKUP_ENABLED false Database backups scheduler + dashboard triggers; CLI always available
BACKUP_NAME — default: APP_NAME
BACKUP_DIR backups relative paths resolve under APP_STORAGE_DIR
BACKUP_DESTINATIONS local local is always included; add s3 for S3/R2/MinIO
BACKUP_S3_PREFIX backups Optional. object key prefix: //
BACKUP_PG_DUMP_PATH pg_dump Optional. host binary; must match the server major version
BACKUP_TIMEOUT 1h Optional.
BACKUP_RUN_CRON 30 1 * * * Optional.
BACKUP_CLEAN_CRON 30 2 * * * Optional.
BACKUP_KEEP_ALL_DAYS 7 Optional.
BACKUP_KEEP_DAILY_DAYS 16 Optional.
BACKUP_KEEP_WEEKLY_WEEKS 8 Optional.
BACKUP_KEEP_MONTHLY_MONTHS 4 Optional.
BACKUP_KEEP_YEARLY_YEARS 2 Optional.
BACKUP_MAX_TOTAL_MB 0 Optional. 0 = unlimited
BACKUP_MAX_AGE_HOURS 26 Optional.
BACKUP_INCLUDE_FILES false Optional.
BACKUP_FILES_PATHS storage/public,storage/private Optional.