Environment configuration

Configure Stratus POS using the .env file — application settings, database, mail, session, queue, and cache.

Stratus uses a .env file at the project root to manage all environment-specific configuration. This file is never committed to version control and must be created on each machine or server where Stratus runs.

Never commit your .env file to version control. It contains secrets such as APP_KEY, database credentials, and mail passwords. Add .env to your .gitignore file.

Creating the .env file

The repository ships with a .env.example template. Copy it to create your local configuration:

cp .env.example .env

Then generate a unique application key:

php artisan key:generate

This writes a base64-encoded key to APP_KEY. Without this key, encrypted values (including sessions and cookies) cannot be decrypted.

The composer run setup command copies .env.example to .env and runs key:generate automatically for first-time installs.

Application variables

These variables control the core identity and behaviour of the application.

APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

APP_MAINTENANCE_DRIVER=file

BCRYPT_ROUNDS=12

Variable	Description
APP_NAME	Display name used in notifications and emails. Change to your application’s name.
APP_ENV	Current environment: local, staging, or production.
APP_KEY	Encryption key. Generate with php artisan key:generate.
APP_DEBUG	Set to false in production to suppress stack traces.
APP_URL	Full base URL including scheme. Used for link generation.
APP_LOCALE	Default locale for translations (default: en).
APP_FALLBACK_LOCALE	Fallback locale if translation is missing (default: en).
APP_FAKER_LOCALE	Locale used by Faker in factories and tests (default: en_US).
APP_MAINTENANCE_DRIVER	How maintenance mode is tracked — file (default) or database.
BCRYPT_ROUNDS	Number of bcrypt hashing rounds for passwords (default: 12). Higher values are slower but more secure.

Always set APP_DEBUG=false and APP_ENV=production on production servers. Leaving debug mode enabled exposes sensitive application internals.

Database configuration

See Database setup for the full guide. The key variables are:

MySQL (default)

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=stratus
DB_USERNAME=root
DB_PASSWORD=

Mail configuration

Mail is required for features such as email verification and password reset.

MAIL_MAILER=log
MAIL_SCHEME=null
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS="[e-mail]"
MAIL_FROM_NAME="${APP_NAME}"

The default MAIL_MAILER=log writes all outgoing mail to the Laravel log file (storage/logs/laravel.log). This is safe for local development — no emails are sent to real inboxes. For production, configure an SMTP provider.

Example: sending via SMTP (e.g. Mailgun, SES, Postmark)

MAIL_MAILER=smtp
MAIL_SCHEME=tls
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=[e-mail]
MAIL_PASSWORD=your-mailgun-password
MAIL_FROM_ADDRESS="[e-mail]"
MAIL_FROM_NAME="Stratus"

Example: Mailpit for local development

Mailpit is a local mail catcher bundled with Laravel Sail. Configure it to capture emails in a web UI without sending them:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null

Session configuration

SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null

SESSION_DRIVER=database stores sessions in the sessions table, which is created by the default migrations. This is the default and works reliably on single-server and multi-server setups alike.

Variable	Description
SESSION_DRIVER	Where sessions are stored: database (default), file, cookie, redis, memcached.
SESSION_LIFETIME	Minutes of inactivity before a session expires (default: 120).
SESSION_ENCRYPT	Encrypt session payloads at rest (default: false).
SESSION_PATH	Cookie path scope (default: /).
SESSION_DOMAIN	Cookie domain scope (default: null, uses current host).

The database driver requires the sessions table to exist. Run php artisan migrate before starting the application.

Queue configuration

QUEUE_CONNECTION=database

Value	Behaviour
database	Jobs are queued in the jobs table and processed by a queue worker. This is the default.
sync	Jobs run immediately in the same process. No worker needed. Useful for simple local setups.

When using database (the default), run the queue worker with:

php artisan queue:work

See Deployment for running the worker as a supervised process.

Cache configuration

CACHE_STORE=database

The default database cache driver stores cached data in the cache table created by migrations. No additional services are required.

Value	Description
database	Cache stored in the cache table (default).
file	Cache stored in storage/framework/cache.
redis	Recommended for high-traffic production environments.
memcached	High-performance in-memory cache. Requires MEMCACHED_HOST.

Redis configuration

Redis can be used as a driver for sessions, cache, and queues. Configure the connection with:

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

To use Redis for cache and sessions:

CACHE_STORE=redis
SESSION_DRIVER=redis

Frontend

VITE_APP_NAME="${APP_NAME}"

VITE_APP_NAME exposes the application name to Vite and the JavaScript frontend. Variables prefixed with VITE_ are the only .env values accessible in browser-side JavaScript.

Logging

LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

Set LOG_LEVEL=error or LOG_LEVEL=warning in production to reduce log volume. Available levels follow RFC 5424: debug, info, notice, warning, error, critical, alert, emergency.