📂 File Permissions & Storage

Proper file permissions are essential for Monitron SaaS to work correctly and securely. This page explains everything you need to know.

---

🗂️ Directory Structure

Here are the key directories and what they're used for:

monitron/
├── storage/
│   ├── app/              # Application files (uploads, exports)
│   │   └── public/       # Publicly accessible uploads
│   ├── framework/
│   │   ├── cache/        # Application cache
│   │   ├── sessions/     # User sessions
│   │   └── views/        # Compiled Blade views
│   └── logs/             # Application logs
│       └── laravel.log   # Main log file
├── bootstrap/
│   └── cache/            # Framework bootstrap cache
│       ├── packages.php
│       └── services.php
└── public/               # Web root (web server points here)

---

🔑 Permission Rules

The Golden Rule

The web server user must own and be able to write to storage/ and bootstrap/cache/.

Everything else should be readable but not writable by the web server.

Recommended Permissions

# Navigate to your Monitron installation
cd /var/www/monitron

# Set the owner to your web server user
# Ubuntu/Debian (Nginx or Apache):
sudo chown -R www-data:www-data .

# CentOS/RHEL (Nginx):
sudo chown -R nginx:nginx .

# Set directory permissions
sudo find . -type d -exec chmod 755 {} \;

# Set file permissions
sudo find . -type f -exec chmod 644 {} \;

# Make storage and cache writable
sudo chmod -R 775 storage/
sudo chmod -R 775 bootstrap/cache/

# Ensure the storage link exists
php artisan storage:link

What Each Permission Means

Permission	Meaning
755 (directories)	Owner: full access. Group/Others: read + execute
644 (files)	Owner: read + write. Group/Others: read only
775 (storage dirs)	Owner + Group: full access. Others: read + execute

---

🔗 The Storage Link

Laravel uses a symbolic link to make files in storage/app/public/ accessible via the web. Create it with:

php artisan storage:link

This creates:

public/storage → storage/app/public

info

What needs the storage link? Status page logos, user avatars, and any uploaded files. If images appear broken on your status pages, the storage link is probably missing!

---

📝 The .env File

Your .env file contains sensitive information (database passwords, API keys, etc.).

# Make sure it's not readable by others
chmod 640 .env

danger

NEVER make .env publicly accessible! Your web server must point to the public/ directory, NOT the root directory. If someone can access https://your-domain.com/.env, your database credentials and API keys are exposed!

Verify .env is Protected

Try accessing it in your browser:

https://your-domain.com/.env

You should get a 403 Forbidden or 404 Not Found error. If you see the file contents, your web server is misconfigured!

---

🐧 Linux: Finding Your Web Server User

Not sure which user your web server runs as? Here's how to find out:

# For Nginx
ps aux | grep nginx

# For Apache
ps aux | grep apache2
# or
ps aux | grep httpd

# For PHP-FPM
ps aux | grep php-fpm

Common web server users:

Distro	Nginx	Apache
Ubuntu/Debian	www-data	www-data
CentOS/RHEL	nginx	apache
Arch Linux	http	http

---

🪟 Windows: Permissions

On Windows (IIS), the IIS_IUSRS group needs:

• Read & Execute on the entire Monitron directory
• Modify on storage/ and bootstrap/cache/

Right-click the folders → Properties → Security tab → Edit → Add IIS_IUSRS with the appropriate permissions.

---

🔧 Troubleshooting Permissions

"The stream or file could not be opened"

UnexpectedValueException: The stream or file "storage/logs/laravel.log"
could not be opened in append mode: Failed to open stream: Permission denied

Fix:

sudo chown -R www-data:www-data storage/
sudo chmod -R 775 storage/

"Unable to create the cache directory"

InvalidArgumentException: Unable to create the cache directory (bootstrap/cache)

Fix:

sudo chown -R www-data:www-data bootstrap/cache/
sudo chmod -R 775 bootstrap/cache/

"View compiled file not found"

# Clear compiled views and rebuild
php artisan view:clear
php artisan config:clear
php artisan cache:clear

Storage link broken after deployment

# Remove old link and recreate
rm -f public/storage
php artisan storage:link