Laravel Linux Setup

Automated installation and configuration script for Laravel development environment on Ubuntu/Debian Linux.

Features

• Apache - Latest stable version with required modules
• PHP 8.3 (default) + PHP 8.4 - With all Laravel required extensions
• Additional PHP Versions - Easy script to install any PHP version (8.1, 8.2, etc.)
• MariaDB - Latest stable version with passwordless root access
• Node.js LTS - Installed via NVM for frontend asset compilation
• Auto VHost Generation - Automatically creates virtual hosts when you add projects
• File Monitoring - Systemd service watches your projects directory
• Composer - Latest version with Laravel installer included
• Per-Project PHP Versions - Each project can use different PHP versions

Quick Install

Recommended method:

git clone https://github.com/adods/laravel-linux-setup.git
cd laravel-linux-setup
./install.sh

Important: Clone the repository instead of just downloading install.sh to ensure all required script modules are available.

Requirements

• Debian-based Linux distribution (Ubuntu, Debian, Linux Mint, Pop!_OS, etc.)
• APT package manager
• Non-root user with sudo privileges
• Systemd init system
• Active internet connection

What Gets Installed

Apache

• Latest stable Apache2
• Enabled modules: rewrite, proxy, proxy_fcgi, ssl, headers

PHP

• PHP 8.3 (set as default)
• PHP 8.4 (available for projects that need it)
• PHP-FPM for both versions
• Extensions: cli, fpm, mysql, pgsql, sqlite3, mbstring, xml, bcmath, curl, zip, gd, intl, soap, redis, memcached, imagick

MariaDB

• Latest stable MariaDB server
• Configured for passwordless root access (unix_socket authentication)
• Secure installation applied
• Test database removed

Auto VHost System

• Monitors your projects directory
• Automatically creates <project-name>.test domains
• Auto-detects Laravel projects (points to /public)
• Falls back to detecting index.php/index.html in standard locations
• Runs as systemd user service (starts on boot)

Composer

• Latest stable version
• Installed globally
• Laravel installer included (laravel new command available)

Node.js

• Installed via NVM (Node Version Manager)
• LTS version set as default
• npm included for frontend asset compilation (Vite, etc.)

Usage

After Installation

1. Create or copy a Laravel project to your projects directory:

   cd ~/Projects  # Or your custom path
   laravel new myapp

2. Your site is automatically available at:

   http://myapp.test
   

3. That's it! The vhost is created automatically.

Manual VHost Creation

If you need to manually create a vhost:

# With default PHP 8.3
create-vhost.sh /path/to/project

# With PHP 8.4
create-vhost.sh /path/to/project 8.4

Database Access

Connect to MariaDB without password:

sudo mysql

Or:

mysql -u root

Managing the Watcher Service

# Check status
systemctl --user status herd-watcher

# View logs
journalctl --user -u herd-watcher -f

# Restart
systemctl --user restart herd-watcher

# Stop
systemctl --user stop herd-watcher

Switching PHP CLI Version

# Interactive selection
sudo update-alternatives --config php

# Direct switch to PHP 8.3
sudo update-alternatives --set php /usr/bin/php8.3

# Direct switch to PHP 8.4
sudo update-alternatives --set php /usr/bin/php8.4

Using Different PHP Versions Per Project

Each project can use a different PHP version. When creating a vhost manually, specify the PHP version:

# Project A uses PHP 8.3
create-vhost.sh ~/Projects/projectA 8.3

# Project B uses PHP 8.4
create-vhost.sh ~/Projects/projectB 8.4

The auto-watcher uses PHP 8.3 by default.

Installing Additional PHP Versions

You can install any specific PHP version with all Laravel extensions using the install-php-version.sh script:

# Install PHP 8.2 using system packages
./bin/install-php-version.sh 8.2

# Install PHP 8.1 using Sury repository (more versions available)
./bin/install-php-version.sh 8.1 --with-sury

# View help and all options
./bin/install-php-version.sh --help

What it installs:

• PHP core (cli, fpm, common)
• All Laravel required extensions: mysql, pgsql, sqlite3, mbstring, xml, bcmath, curl, zip, gd, intl, soap, redis, memcached, imagick
• PHP-FPM service (enabled and started)

Options:

• --with-sury - Use Sury repository for latest PHP versions (8.1, 8.2, 8.3, 8.4, etc.)
• Without flag - Uses system packages (more stable, limited versions)

After installation:

• Use with create-vhost.sh: create-vhost.sh /path/to/project 8.2
• Set as default CLI: sudo update-alternatives --set php /usr/bin/php8.2
• Check installed modules: php8.2 -m

Directory Structure

laravel-linux-setup/
├── install.sh              # Main installation script
├── bin/                    # User-facing scripts
│   ├── create-vhost.sh
│   ├── herd-watcher.sh
│   └── install-php-version.sh  # Install specific PHP versions
├── scripts/                # Installation modules
│   ├── install-apache.sh
│   ├── install-php.sh
│   ├── install-mariadb.sh
│   ├── setup-vhost.sh
│   └── setup-permissions.sh
├── config/                 # Configuration files
├── README.md
└── TODO.md

Troubleshooting

Site shows 500 error

Cause: Missing PHP extensions or Laravel not configured.

Solution:

cd /path/to/your/project
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate

Site shows 403 Forbidden

Cause: Permission issues.

Solution:

# Fix permissions
sudo chown -R $USER:www-data /path/to/project
sudo chmod -R 775 /path/to/project
sudo find /path/to/project -type d -exec chmod g+s {} \;

# Ensure Apache can read the directory
sudo chmod 755 /path/to/project

Watcher not detecting new projects

Check service status:

systemctl --user status herd-watcher

View logs:

journalctl --user -u herd-watcher -f

Restart service:

systemctl --user restart herd-watcher

Group changes not taking effect

You need to log out and log back in for group membership changes to take effect.

Or run:

newgrp www-data

Can't connect to MariaDB

As root:

sudo mysql

Check if service is running:

sudo systemctl status mariadb

Configuration

Change Monitored Directory

Edit the watcher script:

nano ~/.local/bin/herd-watcher.sh

Change the WATCH_DIR variable.

Change Default PHP Version

Edit:

nano ~/.local/bin/herd-watcher.sh

Change PHP_VERSION variable.

Add Custom Apache Configuration

Place your custom configs in:

/etc/apache2/conf-available/

Then enable:

sudo a2enconf your-config
sudo systemctl reload apache2

Uninstallation

To remove everything:

# Stop services
systemctl --user stop herd-watcher
systemctl --user disable herd-watcher

# Remove packages (optional)
sudo apt remove --purge apache2 php8.* mariadb-server

# Remove configuration
rm -rf ~/.local/bin/herd-watcher.sh
rm -rf ~/.config/systemd/user/herd-watcher.service
sudo rm /usr/local/bin/create-vhost.sh
sudo rm /etc/sudoers.d/vhost-management

# Reload
systemctl --user daemon-reload

FAQ

Q: Can I use this on production servers? A: No. This is designed for local development only. The passwordless sudo and other configurations are insecure for production.

Q: Can I use Nginx instead of Apache? A: Not yet. Support for Nginx may be added in the future.

Q: What if I want PostgreSQL instead of MariaDB? A: You can manually install PostgreSQL after running the setup. Future versions may include this option.

Q: Can I use custom TLDs (not .test)? A: Yes, edit the vhost creation script to change the domain suffix.

Q: Does this work on WSL2? A: It should work, but hasn't been extensively tested. File permissions might need adjustment.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - Feel free to use and modify as needed.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Credits

Created for Laravel developers who want a hassle-free local development setup on Linux.

---

Happy coding! 🚀