Installation on Nginx

This guide will walk you through installing Growstack CRM on a server running Nginx web server.

---

Table of Contents

1. Prerequisites
2. Step 1: Server Preparation
3. Step 2: Install PHP and Extensions
4. Step 3: Install Composer and Node.js
5. Step 4: Create Database
6. Step 5: Upload Files
7. Step 6: Configure Nginx
8. Step 7: Set Permissions
9. Step 8: Run the Installer
10. Step 9: Post-Installation
11. Troubleshooting

---

Prerequisites

Before starting, ensure you have:

• ✅ Root or sudo access to server
• ✅ Nginx installed and running
• ✅ PHP 8.2+ installed
• ✅ MySQL/PostgreSQL database server
• ✅ Domain or IP address configured
• ✅ Reviewed System Requirements

---

Step 1: Server Preparation

Update System Packages

Ubuntu/Debian:

sudo apt update
sudo apt upgrade -y

CentOS/RHEL:

sudo yum update -y

Install Required Tools

Ubuntu/Debian:

sudo apt install -y curl wget git unzip

CentOS/RHEL:

sudo yum install -y curl wget git unzip

---

Step 2: Install PHP and Extensions

Install PHP 8.2+

Ubuntu 22.04+:

sudo apt install -y php8.2 php8.2-fpm php8.2-cli

Ubuntu 20.04:

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.2 php8.2-fpm php8.2-cli

CentOS/RHEL:

sudo yum install -y epel-release
sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm
sudo yum module reset php
sudo yum module enable php:remi-8.2
sudo yum install -y php php-fpm php-cli

Install Required PHP Extensions

Ubuntu/Debian:

sudo apt install -y \
    php8.2-mysql \
    php8.2-pgsql \
    php8.2-mbstring \
    php8.2-xml \
    php8.2-curl \
    php8.2-intl \
    php8.2-zip \
    php8.2-gd \
    php8.2-bcmath \
    php8.2-opcache

CentOS/RHEL:

sudo yum install -y \
    php-mysqlnd \
    php-pgsql \
    php-mbstring \
    php-xml \
    php-curl \
    php-intl \
    php-zip \
    php-gd \
    php-bcmath \
    php-opcache

Verify PHP Installation

php -v
# Should show PHP 8.2.0 or higher

php -m
# Should show all required extensions

Configure PHP-FPM

Edit PHP-FPM configuration:

sudo nano /etc/php/8.2/fpm/php.ini

Update these settings:

memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
date.timezone = UTC  # Set your timezone

Restart PHP-FPM:

sudo systemctl restart php8.2-fpm
sudo systemctl enable php8.2-fpm

---

Step 3: Install Composer and Node.js

Install Composer

cd /tmp
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer
composer --version

Install Node.js and NPM

Using NodeSource (Recommended):

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Or using NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

Verify Installation:

node --version  # Should show v18.x or higher
npm --version

---

Step 4: Create Database

MySQL/MariaDB

Login to MySQL:

sudo mysql -u root -p

Create Database and User:

CREATE DATABASE growstack_crm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'growstack_crm_user'@'localhost' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON growstack_crm.* TO 'growstack_crm_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Note: Replace strong_password_here with a secure password.

PostgreSQL

Login to PostgreSQL:

sudo -u postgres psql

Create Database and User:

CREATE DATABASE growstack_crm;
CREATE USER growstack_crm_user WITH PASSWORD 'strong_password_here';
GRANT ALL PRIVILEGES ON DATABASE growstack_crm TO growstack_crm_user;
\q

---

Step 5: Upload Files

Option A: Upload and Extract (Recommended)

cd /var/www
sudo mkdir growstack-crm
# Upload ZIP file via SCP/SFTP, then:
sudo unzip growstack-crm.zip -d growstack-crm

Option B: Using SCP

scp growstack-crm.zip user@yourserver:/var/www/
ssh user@yourserver
cd /var/www && sudo unzip growstack-crm.zip -d growstack-crm

Set Ownership

sudo chown -R www-data:www-data /var/www/growstack-crm

---

Step 6: Configure Nginx

Create Nginx Configuration

Create configuration file:

sudo nano /etc/nginx/sites-available/growstack-crm

Add the following configuration:

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/growstack-crm/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

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

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

Important: Replace yourdomain.com with your actual domain.

Enable Site

sudo ln -s /etc/nginx/sites-available/growstack-crm /etc/nginx/sites-enabled/
sudo nginx -t  # Test configuration
sudo systemctl reload nginx

Test Nginx Configuration

sudo nginx -t

Should show: syntax is ok and test is successful

---

Step 7: Set Permissions

Set Directory Permissions

cd /var/www/growstack-crm
sudo chown -R www-data:www-data .
sudo find . -type d -exec chmod 755 {} \;
sudo find . -type f -exec chmod 644 {} \;

Set Writable Directories

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

Set Executable Files

sudo chmod +x artisan

---

Step 8: Run the Installer

Access the Installer

1. Open browser
2. Navigate to: http://yourdomain.com/install

Follow Installer Steps

See Web Installer Guide for detailed steps.

Quick Summary:

1. Requirements check
2. License verification
3. Environment configuration
4. Database configuration (use growstack_crm as database name)
5. Admin account setup
6. Installation progress
7. Completion

---

Step 9: Post-Installation

Install Dependencies (if needed)

If installer doesn't handle this automatically:

cd /var/www/growstack-crm
composer install --no-dev --optimize-autoloader
npm install
npm run build

Set Up SSL (Let's Encrypt)

Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Obtain Certificate:

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Auto-Renewal:

sudo certbot renew --dry-run

Configure Cron Jobs

Edit crontab:

sudo crontab -e -u www-data

Add:

* * * * * cd /var/www/growstack-crm && php artisan schedule:run >> /dev/null 2>&1

Set Up Queue Worker

Using Supervisor (Recommended):

1. Install Supervisor:

sudo apt install -y supervisor

2. Create config:

sudo nano /etc/supervisor/conf.d/growstack-crm-worker.conf

3. Add configuration:

[program:growstack-crm-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/growstack-crm/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/growstack-crm/storage/logs/worker.log
stopwaitsecs=3600

4. Start Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start growstack-crm-worker:*

---

Troubleshooting

502 Bad Gateway

Problem: PHP-FPM not running or misconfigured

Solutions:

1. Check PHP-FPM status:

   sudo systemctl status php8.2-fpm
   

2. Restart PHP-FPM:

   sudo systemctl restart php8.2-fpm
   

3. Verify socket path in Nginx config matches PHP-FPM config

4. Check PHP-FPM socket:

   ls -la /var/run/php/php8.2-fpm.sock
   

404 Not Found

Problem: Nginx can't find files

Solutions:

1. Verify root path in Nginx config points to /var/www/growstack-crm/public
2. Check file permissions
3. Verify index.php exists in public/ directory
4. Check Nginx error logs:

   sudo tail -f /var/log/nginx/error.log
   

Permission Denied

Problem: Web server can't access files

Solutions:

1. Fix ownership:

   sudo chown -R www-data:www-data /var/www/growstack-crm
   

2. Fix permissions:

   sudo chmod -R 755 /var/www/growstack-crm
   sudo chmod -R 775 storage bootstrap/cache
   

---

Performance Optimization

Enable Gzip Compression

Add to Nginx config:

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json;

Enable Browser Caching

Add to Nginx config:

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

---

Security Recommendations

Firewall Configuration

UFW (Ubuntu):

sudo ufw allow 'Nginx Full'
sudo ufw allow OpenSSH
sudo ufw enable

Nginx Security Headers

Add to server block:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;

---

Next Steps

After successful installation:

1. Review Post-Installation Setup
2. Configure General Settings
3. Set up Email Settings
4. Read Getting Started Guide