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