Configuration

After installing ShelfWise, configure the application settings to match your deployment environment.

Environment Configuration

All configuration is managed through the .env file in your project root. This file is created by copying .env.example:

cp .env.example .env

Never commit .env to version control. It contains sensitive credentials.

Core Application Settings

Application Identity

.env

APP_NAME=ShelfWise
APP_ENV=production
APP_KEY=base64:generated_key_here
APP_DEBUG=false
APP_URL=https://yourdomain.com

Generate APP_KEY with php artisan key:generate. This key encrypts session data, cookies, and other sensitive information.

Configuration Options:

APP_ENV: Set to local, staging, or production
APP_DEBUG: Must be false in production to prevent exposing sensitive data
APP_URL: Your application’s public URL (used in emails, PDFs, and API responses)

Locale and Timezone

.env

APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US
APP_TIMEZONE=UTC

For timezone configuration, edit config/app.php:

config/app.php

'timezone' => env('APP_TIMEZONE', 'UTC'),

Store all timestamps in UTC and convert to user’s timezone in the frontend. ShelfWise follows this best practice.

Database Configuration

ShelfWise supports SQLite, MySQL, and PostgreSQL.

MySQL (Recommended)
PostgreSQL
SQLite (Dev Only)

.env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shelfwise
DB_USERNAME=shelfwise_user
DB_PASSWORD=secure_password_here

Optimization for Production:Edit config/database.php to tune MySQL connection:

config/database.php

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => '',
    'strict' => true,
    'engine' => 'InnoDB',
    'options' => extension_loaded('pdo_mysql') ? array_filter([
        PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
        PDO::ATTR_EMULATE_PREPARES => true,
    ]) : [],
],

.env

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=shelfwise
DB_USERNAME=shelfwise_user
DB_PASSWORD=secure_password_here

.env

DB_CONNECTION=sqlite
# DB_DATABASE path is auto-detected as database/database.sqlite

SQLite is suitable for development only. Do not use in production.

Queue Configuration

ShelfWise uses queues for background jobs like sending emails, generating reports, and processing exports.

Queue Driver Options

Database (Development)
Redis (Production)

Uses the database for queue storage. Suitable for development and small deployments.

.env

QUEUE_CONNECTION=database

Run the queue worker:

php artisan queue:work

Or use the dev script which includes queue worker:

composer dev

Recommended for production. Much faster than database queues.

.env

QUEUE_CONNECTION=redis

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

Install Redis PHP extension:

sudo apt install php8.2-redis
sudo systemctl restart php8.2-fpm

Set up Supervisor for queue workers:Create /etc/supervisor/conf.d/shelfwise-worker.conf:

[program:shelfwise-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/shelfwise/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=4
redirect_stderr=true
stdout_logfile=/var/www/shelfwise/storage/logs/worker.log
stopwaitsecs=3600

Start workers:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start shelfwise-worker:*

Queue Monitoring

Restart queue workers after deploying code changes:

php artisan queue:restart

Cache Configuration

Caching improves performance by storing frequently accessed data in memory.

Database (Development)
Redis (Production)

.env

CACHE_STORE=database

Create cache table:

php artisan cache:table
php artisan migrate

.env

CACHE_STORE=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Redis provides significant performance improvements for cache operations.

Cache Commands

# Clear application cache
php artisan cache:clear

# Cache configuration files (production)
php artisan config:cache

# Cache routes (production)
php artisan route:cache

# Cache views (production)
php artisan view:cache

# Clear all caches
php artisan optimize:clear

Run php artisan config:cache in production after any .env changes. Cached config takes precedence over .env values.

Session Configuration

.env

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

Session Driver Options:

database - Store sessions in database (default, requires sessions table)
redis - Store in Redis (recommended for production with Redis)
file - Store in storage/framework/sessions
cookie - Encrypted session data in cookies

ShelfWise uses database sessions by default. The sessions table is created automatically when running migrations.

Mail Configuration

ShelfWise sends emails for:

Password resets
User invitations
Order confirmations
Purchase order notifications
Payslip delivery

SMTP
Log (Development)

.env

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME="${APP_NAME}"

Popular SMTP Providers:

Gmail

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password

Use an App Password instead of your regular Gmail password.

SendGrid

MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your_sendgrid_api_key
MAIL_ENCRYPTION=tls

Mailgun

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=your-domain.mailgun.org
MAILGUN_SECRET=your_api_key
MAILGUN_ENDPOINT=api.mailgun.net

Postmark

MAIL_MAILER=postmark
POSTMARK_TOKEN=your_postmark_token

For local development, log emails instead of sending:

.env

MAIL_MAILER=log

Emails are written to storage/logs/laravel.log.

You can view logged emails easily using Laravel Pail:

php artisan pail

Test Email Configuration

Verify your mail setup:

php artisan tinker

Mail::raw('Test email from ShelfWise', function ($message) {
    $message->to('[email protected]')
            ->subject('Test Email');
});

File Storage Configuration

ShelfWise stores:

Product images
Tenant logos
User avatars
Generated PDFs and reports
Imported files

.env

FILESYSTEM_DISK=local

Storage Options

Local (Default)
Amazon S3

Files are stored in storage/app.

.env

FILESYSTEM_DISK=local

Create symlink for public access:

php artisan storage:link

This creates public/storage -> storage/app/public.

Store files in AWS S3:

.env

FILESYSTEM_DISK=s3

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name
AWS_USE_PATH_STYLE_ENDPOINT=false

Install AWS SDK:

composer require league/flysystem-aws-s3-v3 "^3.0"

Logging Configuration

.env

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

Log Levels:

debug - Detailed debug information (development)
info - Interesting events
notice - Normal but significant events
warning - Exceptional occurrences that are not errors
error - Runtime errors (production default)
critical - Critical conditions
alert - Action must be taken immediately
emergency - System is unusable

For production, set LOG_LEVEL=error to reduce log file size.

View Logs

Real-time log viewing:

php artisan pail

Or tail the log file:

tail -f storage/logs/laravel.log

Broadcasting Configuration

ShelfWise supports real-time features via Laravel’s broadcasting (future feature).

.env

BROADCAST_CONNECTION=log

For production real-time features:

Use Pusher or Ably
Or self-host with Laravel Reverb
Or use Redis with Laravel Echo Server

Security Settings

Password Hashing

.env

BCRYPT_ROUNDS=12

Higher rounds = more secure but slower. 12 is a good balance. Don’t set below 10.

Maintenance Mode

Put application in maintenance mode during updates:

# Enable maintenance mode
php artisan down --secret=your-secret-bypass-token

# Perform updates...

# Disable maintenance mode
php artisan up

Access site during maintenance:

https://yourdomain.com/your-secret-bypass-token

Performance Optimization

Production Optimizations

Run these commands after deployment:

# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

OPcache Configuration

Enable OPcache in production. Edit php.ini:

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=60
opcache.fast_shutdown=1

Restart PHP-FPM:

sudo systemctl restart php8.2-fpm

Environment-Specific Configs

APP_ENV=local
APP_DEBUG=true
DB_CONNECTION=sqlite
QUEUE_CONNECTION=database
CACHE_STORE=database
MAIL_MAILER=log
LOG_LEVEL=debug

Configuration Verification

Check your configuration:

# View all config values
php artisan config:show

# View specific config
php artisan config:show database
php artisan config:show mail

# Check environment
php artisan about

The php artisan about command shows a summary of your application environment, including PHP version, database connection, cache driver, and more.

Next Steps

Multi-Tenancy Setup

Learn how ShelfWise isolates tenant data and implements role-based access control

API Documentation

Integrate with the service layer API

Introduction

Setup

Environment Configuration

Core Application Settings

Application Identity

Locale and Timezone

Database Configuration

Queue Configuration

Queue Driver Options

Queue Monitoring

Cache Configuration

Cache Commands

Session Configuration

Mail Configuration

Test Email Configuration

File Storage Configuration

Storage Options

Logging Configuration

View Logs

Broadcasting Configuration

Security Settings

Password Hashing

Maintenance Mode

Performance Optimization

Production Optimizations

OPcache Configuration

Environment-Specific Configs

Configuration Verification

Next Steps

Multi-Tenancy Setup

API Documentation

Build docs developers (and LLMs) love

Introduction

Setup

​Environment Configuration

​Core Application Settings

​Application Identity

​Locale and Timezone

​Database Configuration

​Queue Configuration

​Queue Driver Options

​Queue Monitoring

​Cache Configuration

​Cache Commands

​Session Configuration

​Mail Configuration

​Test Email Configuration

​File Storage Configuration

​Storage Options

​Logging Configuration

​View Logs

​Broadcasting Configuration

​Security Settings

​Password Hashing

​Maintenance Mode

​Performance Optimization

​Production Optimizations

​OPcache Configuration

​Environment-Specific Configs

​Configuration Verification

​Next Steps

Multi-Tenancy Setup

API Documentation

Build docs developers (and LLMs) love

Environment Configuration

Core Application Settings

Application Identity

Locale and Timezone

Database Configuration

Queue Configuration

Queue Driver Options

Queue Monitoring

Cache Configuration

Cache Commands

Session Configuration

Mail Configuration

Test Email Configuration

File Storage Configuration

Storage Options

Logging Configuration

View Logs

Broadcasting Configuration

Security Settings

Password Hashing

Maintenance Mode

Performance Optimization

Production Optimizations

OPcache Configuration

Environment-Specific Configs

Configuration Verification

Next Steps