bikeservice/deployment-guide.md

Deployment Guide for Bike Service Application

This guide will help you deploy your Laravel + Vue.js application to an Ubuntu server.

Prerequisites

wwthe

• Ubuntu 20.04+ server with root/sudo access
• Domain name (optional but recommended)
• SSH access to your server

Server Setup

1. Update System

sudo apt update && sudo apt upgrade -y

2. Install Required Software

# Install Nginx
sudo apt install nginx -y

# Install PHP 8.2 and extensions
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install php8.2-fpm php8.2-mysql php8.2-sqlite3 php8.2-xml php8.2-mbstring php8.2-curl php8.2-zip php8.2-gd php8.2-cli php8.2-common php8.2-bcmath php8.2-json php8.2-tokenizer php8.2-fileinfo -y

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Install Node.js and npm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Git
sudo apt install git -y

# Install SQLite (if using SQLite)
sudo apt install sqlite3 -y

3. Configure PHP-FPM

# Edit PHP-FPM configuration
sudo nano /etc/php/8.2/fpm/php.ini

# Set these values:
# memory_limit = 256M
# upload_max_filesize = 64M
# post_max_size = 64M
# max_execution_time = 300

# Restart PHP-FPM
sudo systemctl restart php8.2-fpm
sudo systemctl enable php8.2-fpm

Application Deployment

1. Create Application Directory

sudo mkdir -p /var/www/bikeservice
sudo chown -R $USER:$USER /var/www/bikeservice
cd /var/www/bikeservice

2. Clone Your Repository

git clone <your-repository-url> .
# Or upload your files via SCP/SFTP

3. Backend Setup (Laravel)

cd backend

# Install dependencies
composer install --no-dev --optimize-autoloader

# Set permissions
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

# Create .env file
cp .env.example .env

# Generate application key
php artisan key:generate

# Configure database (update .env file)
# For production, consider using MySQL/PostgreSQL instead of SQLite

# Run migrations
php artisan migrate --force

# Clear and cache config
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Set production environment
echo "APP_ENV=production" >> .env
echo "APP_DEBUG=false" >> .env

4. Frontend Setup (Vue.js)

cd ../frontend

# Install dependencies
npm install

# Build for production
npm run build

# Copy built files to Laravel public directory
cp -r dist/* ../backend/public/

Nginx Configuration

1. Create Nginx Site Configuration

sudo nano /etc/nginx/sites-available/bikeservice

Add this configuration:

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    root /var/www/bikeservice/backend/public;
    index index.php index.html index.htm;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

2. Enable Site and Restart Nginx

sudo ln -s /etc/nginx/sites-available/bikeservice /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx

SSL Certificate (Optional but Recommended)

1. Install Certbot

sudo apt install certbot python3-certbot-nginx -y

2. Obtain SSL Certificate

sudo certbot --nginx -d your-domain.com -d www.your-domain.com

Final Configuration

1. Set Proper Permissions

sudo chown -R www-data:www-data /var/www/bikeservice
sudo chmod -R 755 /var/www/bikeservice
sudo chmod -R 775 /var/www/bikeservice/backend/storage
sudo chmod -R 775 /var/www/bikeservice/backend/bootstrap/cache

2. Configure Queue Worker (if using queues)

# Create systemd service for queue worker
sudo nano /etc/systemd/system/bikeservice-queue.service

Add this content:

[Unit]
Description=Bike Service Queue Worker
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/bikeservice/backend
ExecStart=/usr/bin/php artisan queue:work --sleep=3 --tries=3 --max-time=3600
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable bikeservice-queue
sudo systemctl start bikeservice-queue

3. Set up Cron for Laravel Scheduler

crontab -e

Add this line:

* * * * * cd /var/www/bikeservice/backend && php artisan schedule:run >> /dev/null 2>&1

Deployment Script

Create a deployment script for future updates:

#!/bin/bash
# deploy.sh

cd /var/www/bikeservice

# Pull latest changes
git pull origin main

# Backend deployment
cd backend
composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Frontend deployment
cd ../frontend
npm install
npm run build
cp -r dist/* ../backend/public/

# Set permissions
sudo chown -R www-data:www-data /var/www/bikeservice
sudo chmod -R 755 /var/www/bikeservice
sudo chmod -R 775 /var/www/bikeservice/backend/storage
sudo chmod -R 775 /var/www/bikeservice/backend/bootstrap/cache

# Restart services
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

echo "Deployment completed!"

Make it executable:

chmod +x deploy.sh

Monitoring and Maintenance

1. Check Application Status

# Check Nginx status
sudo systemctl status nginx

# Check PHP-FPM status
sudo systemctl status php8.2-fpm

# Check queue worker status
sudo systemctl status bikeservice-queue

# Check Laravel logs
tail -f /var/www/bikeservice/backend/storage/logs/laravel.log

2. Regular Maintenance

# Update system packages
sudo apt update && sudo apt upgrade -y

# Clear Laravel caches
cd /var/www/bikeservice/backend
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Rebuild caches
php artisan config:cache
php artisan route:cache
php artisan view:cache

Troubleshooting

Common Issues:

1. Permission denied errors: Check file ownership and permissions
2. 500 Internal Server Error: Check Laravel logs and PHP-FPM logs
3. Database connection issues: Verify database configuration in .env
4. Static assets not loading: Check Nginx configuration and file paths

Useful Commands:

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Check PHP-FPM logs
sudo tail -f /var/log/php8.2-fpm.log

# Test Nginx configuration
sudo nginx -t

# Restart all services
sudo systemctl restart nginx php8.2-fpm bikeservice-queue

Security Considerations

1. Firewall: Configure UFW firewall
2. SSH: Use key-based authentication and change default port
3. Database: Use strong passwords and limit access
4. Updates: Keep system and packages updated
5. Backups: Set up regular backups of your application and database

Performance Optimization

1. OPcache: Enable PHP OPcache for better performance
2. Redis: Consider using Redis for caching and sessions
3. CDN: Use a CDN for static assets
4. Database: Optimize database queries and indexes
5. Monitoring: Set up application monitoring (Laravel Telescope, etc.)