This document explains how to install and run the Laravel Posts application on a server or local machine.

The application is built with Laravel 12 and requires PHP 8.2 or higher, MySQL or MariaDB, Node.js, and npm.

---

1. Installation Method

This guide uses the release tarball installation method.

Use this method when you want to install the application directly from a GitHub release package.

---

2. System Requirements

Software	Minimum Version	Notes
PHP	8.2 or higher	Required by composer.json using "php": "^8.2"
Composer	2.x	PHP dependency manager. Not required if vendor files are already bundled
MySQL or MariaDB	MySQL 5.7+/8.0 or MariaDB 10.3+	Required. SQLite is not supported for this application
Node.js	20.19+ or 22.12+	Required for npm install and npm run build because the project uses Vite 7
npm	10+	Usually installed with Node.js
Web Server	Apache or PHP built-in server	Apache mod_rewrite must be enabled
Git	Any recent version	Optional, only needed if cloning from repository

---

3. Tech Stack

The application uses the following technologies:

Area	Technology
Backend	Laravel 12
Frontend Build	Vite 7
Styling	Tailwind CSS 4
HTTP Client	Axios
CSS Tools	PostCSS, Autoprefixer
Testing	PHPUnit 11
Development Tools	Pint, Pail, Sail, Tinker, Mockery, Faker, Collision

---

4. Required PHP Extensions

Make sure the following PHP extensions are enabled:

pdo_mysql
mbstring
openssl
tokenizer
xml
ctype
json
bcmath
fileinfo
curl
gd

Important extensions:

Extension	Purpose
pdo_mysql	Required for MySQL or MariaDB database connection
fileinfo	Required for file and image uploads
gd	Recommended for image handling, avatars, and post media
curl	Required for HTTP requests
mbstring	Required by Laravel
openssl	Required for encryption and secure operations

Check your PHP version and enabled extensions:

php -v
php -m

---

5. Windows XAMPP Notes

For Windows users, XAMPP 8.2 or higher is recommended.

XAMPP includes:

Apache
MariaDB/MySQL
PHP 8.2+

However, XAMPP does not include Composer and Node.js.

You need to install separately:

Composer
Node.js
npm

In XAMPP, PHP extensions can be enabled from:

C:\xampp\php\php.ini

Make sure these lines are not commented:

extension=pdo_mysql
extension=fileinfo
extension=mbstring
extension=gd
extension=curl

After changing php.ini, restart Apache from XAMPP Control Panel.

---

6. Database Requirement

This application requires MySQL or MariaDB.

SQLite is not supported for this application because:

The installer uses the mysql driver
The application requires MySQL/MariaDB FULLTEXT index support

Create a database before running the installer.

Example:

CREATE DATABASE laravel_posts_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

You also need a database username and password.

Example:

CREATE USER 'laravel_posts_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON laravel_posts_db.* TO 'laravel_posts_user'@'localhost';
FLUSH PRIVILEGES;

---

7. Full Installation Procedure

Run the following commands step by step.

# 1. Create a working folder and enter it
mkdir -p stories && cd stories

# 2. Download the release tarball
https://github.com/AdarshAshwani/Laravel-Posts/archive/refs/tags/v1.00.011.tar.gz

# 3. Extract the tarball
tar -xvzf v1.00.011.tar.gz

# 4. Enter the extracted folder
cd Laravel-Posts-1.00.010

# 5. Move visible files to the parent folder
mv * ..

# 6. Move tracked dotfiles to the parent folder
mv .editorconfig .env .env.example .gitattributes .gitignore .htaccess .version ..

# 7. Go back to the main installation folder
cd ..

# 8. Remove extracted folder and tarball
rm -rf Laravel-Posts-1.00.011 v1.00.011.tar.gz

# 9. Generate Laravel application key
php artisan key:generate

# 10. Create storage symlink
php artisan storage:link

# 11. Set permissions 
chmod -R 755 .

# 12. Build frontend assets
npm run build

# 13. Install frontend dependencies
npm install

# 14. Protect .env file
chmod 600 .env

# 15. Set ownership to web server user
chown -R daemon:daemon .

---

8. Important Note About Web Server User

The command below sets the project owner to daemon:daemon:

chown -R daemon:daemon .

This is commonly used in XAMPP/LAMPP environments.

However, your web server user may be different depending on your server.

Common web server users:

Server Type	Common User
XAMPP/LAMPP	daemon
Ubuntu Apache	www-data
CentOS Apache	apache
cPanel	Your cPanel username

Examples:

For Ubuntu Apache:

chown -R www-data:www-data .

For CentOS Apache:

chown -R apache:apache .

For cPanel:

chown -R yourcpaneluser:yourcpaneluser .

---

9. Apache VirtualHost Example

Point your Apache VirtualHost to the Laravel public directory.

Example:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /path/to/stories/

    <Directory /path/to/stories/>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/your-domain-error.log
    CustomLog ${APACHE_LOG_DIR}/your-domain-access.log combined
</VirtualHost>

Enable Apache rewrite module:

a2enmod rewrite
systemctl restart apache2

For XAMPP/LAMPP, make sure mod_rewrite is enabled in Apache configuration.

---

10. Complete Web Installer

After completing the command-line setup, open the application in your browser.

Visit:

https://your-domain.com/install

Then complete the web installer.

During installation, enter:

Database host
Database name
Database username
Database password
Admin user details
Website settings

After installation, verify that the home page and admin panel are working properly.

---

11. Frontend Build Notes

This application uses Vite 7.

Node.js must be:

20.19+

or

22.12+

Check your Node.js and npm versions:

node -v
npm -v

If Node.js is older, upgrade Node.js before running:

npm install
npm run build

Older Node.js versions may fail during the Vite build process.

---

13. Storage Permission Notes

Laravel needs write permission for these folders:

storage
bootstrap/cache

Recommended permission:

chmod -R 775 storage bootstrap/cache

If required, set ownership again:

chown -R daemon:daemon storage bootstrap/cache

For Ubuntu Apache:

chown -R www-data:www-data storage bootstrap/cache

---

14. Useful Laravel Commands

Clear cache:

php artisan cache:clear

Clear config cache:

php artisan config:clear

Clear route cache:

php artisan route:clear

Clear view cache:

php artisan view:clear

Generate app key:

php artisan key:generate

Create storage link:

php artisan storage:link

Check routes:

php artisan route:list

---

15. Troubleshooting

Problem: Page shows 500 server error

Run:

php artisan config:clear
php artisan cache:clear
php artisan view:clear

Also check:

storage/logs/laravel.log

---

Problem: CSS or JS not loading

Run:

npm install
npm run build

Make sure the public/build folder exists.

---

Problem: Database connection failed

Check .env database values:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

Then run:

php artisan config:clear

---

Problem: Uploads not working

Make sure fileinfo extension is enabled.

Check:

php -m | grep fileinfo

Also make sure storage link exists:

php artisan storage:link

---

Problem: Permission denied error

Run:

chmod -R 775 storage bootstrap/cache
chown -R daemon:daemon storage bootstrap/cache

Use the correct web server user for your server.

---

16. Final Checklist

Before going live, confirm the following:

PHP version is 8.2 or higher
Required PHP extensions are enabled
MySQL or MariaDB database is created
.env file has correct database details
APP_KEY is generated
storage:link command is completed
npm install is completed
npm run build is completed
Web server points to the public folder
/install page is accessible
File and folder permissions are correct
APP_DEBUG is false in production

Production .env should contain:

APP_ENV=production
APP_DEBUG=false

---

17. Recommended Production Commands

After installation is complete, run:

php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear

Then rebuild frontend assets if needed:

npm install
npm run build

Finally, secure the .env file:

chmod 600 .env

---

Installation Completed

The Laravel Posts application should now be ready.

Open your domain in the browser and complete the installer from:

/install