Skip to content

install-guide.md

Latest commit

 

History

History
346 lines (273 loc) · 7.69 KB

install-guide.md

File metadata and controls

346 lines (273 loc) · 7.69 KB

📋 PUQcloud Installation Guide (install.sh)

Detailed guide for the main PUQcloud installation script on Debian/Ubuntu systems.

🎯 Script Purpose

The install.sh script automates complete PUQcloud installation with all necessary components:

  • Web server (Nginx)
  • PHP 8.2 + extensions
  • MariaDB
  • Redis
  • Laravel Horizon
  • SSL certificates
  • Cron job configuration

🚀 Running Methods

1. Interactive Mode

sudo ./install.sh

The script will prompt for all required parameters.

2. With Command Line Parameters

sudo ./install.sh example.com admin@example.com password123 "Admin Name"

3. Update Existing Installation

sudo ./install.sh
# Choose "update" when prompted

📊 Installation Process Diagram

flowchart TD
    A["Run install.sh"] --> B{"Working mode?"}
    B -->|"install"| C["Check root privileges"]
    B -->|"update"| U["Update mode"]
    
    C --> D["Load previous settings"]
    D --> E["Input parameters"]
    E --> F["Save settings"]
    F --> G["Update system"]
    
    G --> H["Install base packages"]
    H --> I["Install Node.js"]
    I --> J["Install PHP 8.2"]
    J --> K["Install Redis"]
    K --> L["Configure MariaDB"]
    
    L --> M["Install Composer"]
    M --> N["Clone PUQcloud"]
    N --> O["Install dependencies"]
    O --> P["Compile frontend"]
    
    P --> Q["Configure .env"]
    Q --> R["Run migrations"]
    R --> S["Create admin"]
    S --> T["Configure Nginx"]
    
    T --> V{"Domain = hostname?"}
    V -->|"Yes"| W["Configure for all IPs"]
    V -->|"No"| X["Configure for domain"]
    W --> Y["Self-signed SSL"]
    X --> Z["Let's Encrypt SSL"]
    
    Y --> AA["Configure Supervisor"]
    Z --> AA
    AA --> BB["Configure vsftpd"]
    BB --> CC["Configure cron"]
    CC --> DD["Check Horizon"]
    DD --> EE["Installation complete"]
    
    U --> UU["Stop Horizon"]
    UU --> VV["Stop cron"]
    VV --> WW{"Hard update?"}
    WW -->|"Yes"| XX["Rollback migrations"]
    WW -->|"No"| YY["Update code"]
    XX --> YY
    YY --> ZZ["Update dependencies"]
    ZZ --> AAA["Run migrations"]
    AAA --> BBB["Restart services"]
    BBB --> CCC["Update complete"]
Loading

🔧 Installed Components

System Packages

# Base packages
nginx mariadb-server git curl unzip lsb-release ca-certificates sendmail

# PHP and extensions
php8.2 php8.2-fpm php8.2-mysql php8.2-xml php8.2-mbstring 
php8.2-curl php8.2-zip php8.2-bcmath php8.2-redis

# Additional
redis-server nodejs supervisor vsftpd certbot python3-certbot-nginx

Database

  • DB Name: puqcloud_db_[random string]
  • User: puqcloud_user_[random string]
  • Password: automatically generated (12 characters)

⚙️ .env Configuration

The script automatically configures the following parameters:

APP_NAME=PUQcloud
APP_ENV=production
APP_DEBUG=true
APP_TIMEZONE=Europe/Warsaw
APP_URL=http://your-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=puqcloud_db_xxxxxxxx
DB_USERNAME=puqcloud_user_xxxxxxxx
DB_PASSWORD=xxxxxxxxxxxx

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

🌐 Nginx Configuration

For hostname (all IP addresses)

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    listen 443 ssl default_server;
    root /var/www/puqcloud/public;
    
    # SSL configuration with self-signed certificate
    include snippets/self-signed.conf;
    include snippets/ssl-params.conf;
}

For specific domain

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/puqcloud/public;
    
    # Let's Encrypt SSL automatically added
}

# Block IP access
server {
    listen 80 default_server;
    return 444;
}

📂 File Structure

After installation, the following structure is created:

/var/www/puqcloud/
├── app/                 # Laravel application
├── config/             # Configuration
├── database/           # Migrations and seeds
├── public/             # Public files
├── storage/            # Logs and cache
├── .env               # Environment configuration
└── artisan            # Laravel CLI

/etc/nginx/sites-available/
├── default            # Nginx configuration
└── your-domain.com    # Domain configuration

/etc/supervisor/conf.d/
└── horizon.conf       # Horizon configuration

/var/log/
├── nginx/             # Nginx logs
├── php_errors.log     # PHP logs
└── mail.log          # Mail logs

👤 Administrator Creation

The script automatically creates an administrator user:

php artisan puqcloud:seed --email="admin@example.com" \
                          --password="password123" \
                          --name="Admin Name"

🔄 Automatic Tasks

Cron Job

# Added for www-data user
* * * * * cd /var/www/puqcloud/ && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Supervisor (Horizon)

[program:horizon]
process_name=%(program_name)s
command=php /var/www/puqcloud/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/puqcloud/storage/logs/horizon.log

🔒 Security

File Permissions

# Owner of all files
chown -R www-data:www-data /var/www/puqcloud

# Permissions for storage and cache directories
chmod -R 775 /var/www/puqcloud/storage
chmod -R 775 /var/www/puqcloud/bootstrap/cache

SSL Certificates

  • For hostname: Self-signed certificate
  • For domain: Let's Encrypt certificate

Password Generation

# Random string for DB name
tr -dc 'a-zA-Z0-9' </dev/urandom | head -c 8

# Random password for DB
tr -dc 'a-zA-Z0-9' </dev/urandom | head -c 12

📧 Mail Configuration

The script checks and configures sendmail:

  1. Check sendmail installation
  2. Check PHP configuration (sendmail_path)
  3. Send test email
  4. Check logs for errors

🔄 Update Mode

Regular Update

  1. Stop Horizon and cron
  2. Update code from Git
  3. Update dependencies
  4. Compile frontend
  5. Run DB migrations
  6. Restart services

Hard Update

  1. Rollback all migrations
  2. Update code
  3. Update dependencies
  4. Re-run migrations
  5. Recreate administrator

🛠️ FTP Configuration (optional)

When choosing to create an FTP user:

# Create user
useradd -m $ftp_username

# Add to www-data group
usermod -aG www-data $ftp_username

# Set permissions
chown -R www-data:www-data /var/www/puqcloud
chmod -R 775 /var/www/puqcloud

vsftpd Configuration

anonymous_enable=NO
local_enable=YES
write_enable=YES
chroot_local_user=YES
allow_writeable_chroot=YES
listen=YES
local_root=/var/www/puqcloud

🔍 Installation Verification

After completion, check:

  1. Web interface: http://your-domain.com
  2. Horizon status: php artisan horizon:status
  3. Service status: 
    systemctl status nginx
systemctl status php8.2-fpm
systemctl status mariadb
systemctl status redis-server
supervisorctl status horizon

🆘 Troubleshooting

Log Checking

# Installation logs
tail -f /var/log/nginx/error.log
tail -f /var/log/php_errors.log
tail -f /var/www/puqcloud/storage/logs/laravel.log

# Horizon logs
tail -f /var/www/puqcloud/storage/logs/horizon.log

Common Issues

  1. File permissions: sudo chown -R www-data:www-data /var/www/puqcloud
  2. PHP extensions: php -m | grep xml
  3. Database: mysql -u root -p -e "SHOW DATABASES;"
  4. Redis: redis-cli ping

📝 install_config.txt Parameters

The script saves settings for reuse:

HOSTNAME=example.com
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=password123
ADMIN_NAME=Admin Name

This file is used during subsequent runs to suggest previous values.