Configuration
Environment Variables
Full reference for Stilmerce API environment variables.
Environment Variables
Application URLs
| Variable | Required | Description |
|---|---|---|
APP_URL | Yes | API's own public URL |
FRONT_URL | Yes | Storefront public URL |
ADMIN_URL | Yes | Admin panel public URL (include /admin path) |
CORS_ORIGIN | Yes | Comma-separated list of allowed origins |
PORT | No | API port (default: 4000) |
Database (PostgreSQL)
| Variable | Required | Description |
|---|---|---|
DB_HOST | Yes | Database host |
DB_PORT | Yes | Database port (default: 5432) |
DB_USER | Yes | Database username |
DB_PASS | Yes | Database password |
DB_NAME | Yes | Database name |
Redis
| Variable | Required | Description |
|---|---|---|
REDIS_HOST | Yes | Redis host |
REDIS_PORT | Yes | Redis port (default: 6379) |
Security
These values cannot be changed after the first launch — changing them invalidates all existing sessions and password hashes.
| Variable | Required | Description |
|---|---|---|
PASSWORD_PEPPER | Yes | Argon2id pepper, minimum 64 hex characters. Generate with openssl rand -hex 32 |
JWT_ACCESS_SECRET | Yes | JWT signing secret, minimum 32 characters |
JWT_REFRESH_SECRET | Yes | Separate JWT refresh secret |
JWT_ACCESS_EXPIRATION | No | Access token lifetime (default: 7d) |
JWT_REFRESH_EXPIRATION | No | Refresh token lifetime (default: 30d) |
Email (SMTP)
| Variable | Required | Description |
|---|---|---|
MAIL_HOST | Yes | SMTP server hostname |
MAIL_PORT | Yes | SMTP port (typically 587 or 465) |
MAIL_USER | Yes | SMTP username |
MAIL_PASS | Yes | SMTP password |
Payment — İyzico (built-in)
| Variable | Required | Description |
|---|---|---|
IYZICO_API_KEY | Yes | İyzico API key |
IYZICO_SECRET_KEY | Yes | İyzico secret key |
IYZICO_BASE_URL | Yes | https://api.iyzipay.com (live) or https://sandbox-api.iyzipay.com (test) |
IYZICO_SIGNATURE_VALIDATE | No | Validate webhook signatures (default: true) |
File Storage
| Variable | Required | Description |
|---|---|---|
USE_CLOUDINARY | No | true to use Cloudinary, false for local disk storage (default: false) |
CLOUDINARY_CLOUD_NAME | If Cloudinary | Cloudinary cloud name |
CLOUDINARY_API_KEY | If Cloudinary | Cloudinary API key |
CLOUDINARY_API_SECRET | If Cloudinary | Cloudinary API secret |
Search (Typesense)
| Variable | Required | Description |
|---|---|---|
TYPESENSE_ENABLED | No | Enable Typesense search (default: true) |
TYPESENSE_HOST | Yes | Typesense server host |
TYPESENSE_PORT | Yes | Typesense port (default: 8108) |
TYPESENSE_API_KEY | Yes | Typesense admin API key |
TYPESENSE_COLLECTION | No | Collection name (default: products) |
Rate Limiting
| Variable | Required | Description |
|---|---|---|
RATE_LIMIT_ENABLED | No | Enable rate limiting (default: true) |
RATE_LIMIT_DEFAULT_LIMIT | No | Requests per window (default: 300) |
RATE_LIMIT_DEFAULT_WINDOW_SEC | No | Window duration in seconds (default: 60) |
TRUST_PROXY | No | Set true when running behind Nginx (enables X-Forwarded-For) |
Installer & Swagger
| Variable | Description |
|---|---|
INSTALLER_DISABLED | Set true after installation is complete to disable the setup endpoint |
SWAGGER_ENABLED | Enable Swagger UI (default: true in dev) |
SWAGGER_PRODUCTION_ALLOWED | Set true to allow Swagger in production |
SWAGGER_ACCESS_TOKEN | Required when Swagger is enabled in production |
Health Check
| Variable | Description |
|---|---|
HEALTH_ENABLED | Enable health check endpoints (default: true) |
HEALTH_LIVE_TOKEN | Token for the liveness endpoint |
HEALTH_READY_TOKEN | Token for the readiness endpoint |