Last Updated: 3/13/2026

Environment Configuration

LinkAce uses environment variables for configuration, following Laravel conventions. All configuration is managed through the .env file.

Required Configuration

Application Settings


# Application environment (local, production)
APP_ENV=production
 
# Enable debug mode (never in production!)
APP_DEBUG=false
 
# Application URL
APP_URL=https://linkace.example.com
 
# Application key (generated during setup)
APP_KEY=base64:...
 
# API version
APP_API_VERSION=2
 
# API rate limit (requests per minute)
APP_API_RATE_LIMIT=60

Database Configuration

MySQL (Recommended)


DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=linkace
DB_USERNAME=linkace
DB_PASSWORD=ChangeThisToASecurePassword!

PostgreSQL


DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=linkace
DB_USERNAME=linkace
DB_PASSWORD=ChangeThisToASecurePassword!

SQLite


DB_CONNECTION=sqlite
# Database file location
DB_DATABASE=/path/to/database.sqlite

SQL Server


DB_CONNECTION=sqlsrv
DB_HOST=db
DB_PORT=1433
DB_DATABASE=linkace
DB_USERNAME=linkace
DB_PASSWORD=ChangeThisToASecurePassword!

Important: Wrap passwords with special characters in quotes:


DB_PASSWORD="P@ssw0rd!#$"

Optional Configuration

Redis Configuration


# Redis connection
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379
 
# Use Redis for cache
CACHE_DRIVER=redis
 
# Use Redis for sessions
SESSION_DRIVER=redis
 
# Use Redis for queues
QUEUE_CONNECTION=redis

Email Configuration

SMTP


MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="LinkAce"

Mailgun


MAIL_MAILER=mailgun
MAILGUN_DOMAIN=mg.example.com
MAILGUN_SECRET=your-mailgun-api-key
MAILGUN_ENDPOINT=api.mailgun.net
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="LinkAce"

Other Providers

LinkAce supports SendGrid, Amazon SES, Postmark, and other Laravel-compatible mail drivers.

User Registration


# Enable public registration
REGISTRATION_ENABLED=true
 
# Require email verification
MAIL_VERIFICATION=false

Single Sign-On (SSO)


# Enable SSO
SSO_ENABLED=true
 
# Allow new user registration via SSO
SSO_REGISTRATION_ENABLED=true
 
# Disable traditional login when SSO is enabled
REGULAR_LOGIN_DISABLED=false

OAuth Provider Configuration

Each provider requires specific credentials:

Google:


GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://linkace.example.com/auth/google/callback

GitHub:


GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_REDIRECT_URI=https://linkace.example.com/auth/github/callback

Generic OIDC:


OIDC_NAME="My OIDC Provider"
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://linkace.example.com/auth/oidc/callback
OIDC_ISSUER=https://oidc-provider.example.com

Similar patterns apply for Auth0, Authentik, Azure, Cognito, FusionAuth, GitLab, Keycloak, Okta, and Zitadel.

Backup Configuration


# Backup driver (local, s3, ftp, sftp)
BACKUP_DRIVER=local
 
# Backup schedule (daily, weekly)
BACKUP_SCHEDULE=daily
 
# Backup retention (days)
BACKUP_RETENTION_DAYS=7

Amazon S3 Backup


BACKUP_DRIVER=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_ENDPOINT=https://s3.amazonaws.com

FTP Backup


BACKUP_DRIVER=ftp
FTP_HOST=ftp.example.com
FTP_USERNAME=your-username
FTP_PASSWORD=your-password
FTP_PORT=21
FTP_ROOT=/backups
FTP_PASSIVE=true
FTP_SSL=false

SFTP Backup


BACKUP_DRIVER=sftp
SFTP_HOST=sftp.example.com
SFTP_USERNAME=your-username
SFTP_PASSWORD=your-password
SFTP_PORT=22
SFTP_ROOT=/backups
SFTP_PRIVATE_KEY=/path/to/private-key

Internet Archive Integration


# Enable automatic archiving to Wayback Machine
ARCHIVE_BACKUPS_ENABLED=true
 
# Archive private links (requires Internet Archive account)
ARCHIVE_PRIVATE_BACKUPS_ENABLED=false

Error Tracking (Sentry)


# Sentry DSN for error tracking
SENTRY_LARAVEL_DSN=https://your-sentry-dsn@sentry.io/project-id
 
# Sample rate for performance monitoring (0.0 to 1.0)
SENTRY_TRACES_SAMPLE_RATE=0.1

Session Configuration


# Session driver (file, cookie, database, redis)
SESSION_DRIVER=file
 
# Session lifetime (minutes)
SESSION_LIFETIME=120
 
# Encrypt session data
SESSION_ENCRYPT=false
 
# Session cookie name
SESSION_COOKIE=linkace_session
 
# Session cookie domain
SESSION_DOMAIN=null
 
# Secure cookies (HTTPS only)
SESSION_SECURE_COOKIE=false
 
# HTTP-only cookies
SESSION_HTTP_ONLY=true
 
# SameSite cookie policy (lax, strict, none)
SESSION_SAME_SITE=lax

Queue Configuration


# Queue connection (sync, database, redis)
QUEUE_CONNECTION=redis
 
# Queue name prefix
QUEUE_PREFIX=linkace_

Logging


# Log channel (stack, single, daily, syslog, errorlog)
LOG_CHANNEL=stack
 
# Log level (debug, info, notice, warning, error, critical, alert, emergency)
LOG_LEVEL=debug
 
# Slack logging (optional)
LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Trusted Proxies

If running behind a reverse proxy:


# Trust all proxies
TRUSTED_PROXIES=*
 
# Or specify specific proxy IPs
TRUSTED_PROXIES=10.0.0.1,10.0.0.2

HTTPS Configuration


# Force HTTPS
FORCE_HTTPS=true
 
# Force HTTPS in asset URLs
ASSET_URL=https://linkace.example.com

Docker-Specific Configuration

Production Environment File

File: .env.docker.production

Key differences from standard .env:


# Database host matches Docker service name
DB_HOST=db
 
# Redis host matches Docker service name
REDIS_HOST=redis
 
# Use production settings
APP_ENV=production
APP_DEBUG=false

SQLite Docker Configuration

File: .env.sqlite.production


DB_CONNECTION=sqlite
DB_DATABASE=/app/database/database.sqlite

Development Environment File

File: .env.dev


APP_ENV=local
APP_DEBUG=true
LOG_LEVEL=debug

Configuration Caching

In production, cache configuration for better performance:


php artisan config:cache

Clear configuration cache:


php artisan config:clear

Database Collation

LinkAce supports adjusting database collation for better Unicode support:


php artisan linkace:collation:update

See the “Adjusting the Database Collation” guide for details.

Configuration Files

Environment variables map to configuration files in config/:

File	Variables	Purpose
`app.php`	`APP_*`	Application settings
`auth.php`	`SSO_*`	Authentication
`database.php`	`DB_*`	Database connections
`mail.php`	`MAIL_*`	Email configuration
`queue.php`	`QUEUE_*`	Queue configuration
`cache.php`	`CACHE_*`	Cache configuration
`session.php`	`SESSION_*`	Session configuration
`logging.php`	`LOG_*`	Logging configuration
`services.php`	Provider-specific	Third-party services
`filesystems.php`	`AWS_`, `FTP_`, `SFTP_*`	File storage

Security Best Practices

1. Strong APP_KEY

Always generate a secure application key:


php artisan key:generate

2. Secure Database Credentials

Use strong, random passwords
Wrap passwords with special characters in quotes
Never commit .env to version control

3. Disable Debug in Production


APP_DEBUG=false

Debug mode can expose sensitive information.

4. Use HTTPS


FORCE_HTTPS=true
SESSION_SECURE_COOKIE=true

5. Restrict Registration

If you don’t need public registration:


REGISTRATION_ENABLED=false

Use the invitation system instead.

6. Configure Trusted Proxies

If behind a proxy, configure trusted proxies to prevent IP spoofing:


TRUSTED_PROXIES=10.0.0.1

Environment-Specific Settings

Development


APP_ENV=local
APP_DEBUG=true
LOG_LEVEL=debug
MAIL_MAILER=log
QUEUE_CONNECTION=sync

Staging


APP_ENV=staging
APP_DEBUG=false
LOG_LEVEL=info

Production


APP_ENV=production
APP_DEBUG=false
LOG_LEVEL=warning
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

Troubleshooting

Configuration Not Taking Effect

Clear configuration cache:
```
php artisan config:clear
```
Restart web server/PHP-FPM
In Docker, restart containers:
```
docker-compose restart
```

Database Connection Issues

Verify credentials in .env
Check database host is accessible
Ensure database exists and user has permissions
Test connection:
```
php artisan migrate:status
```

Email Not Sending

Verify MAIL_* variables

Test mail configuration:


php artisan tinker
Mail::raw('Test', function($msg) { $msg->to('test@example.com')->subject('Test'); });

Check logs in storage/logs/

Queue Jobs Not Processing

Ensure queue worker is running:
```
php artisan queue:work
```

In Docker, check supervisor status:


docker-compose exec app supervisorctl status

Verify QUEUE_CONNECTION is set correctly