Skip to content

INSTALLATION.md

Latest commit

 

History

History
445 lines (333 loc) · 8.4 KB

INSTALLATION.md

File metadata and controls

445 lines (333 loc) · 8.4 KB

Installation Guide - Fastway Couriers Web Application

This guide provides detailed installation instructions for different server environments.

Quick Start (5 Minutes)

For the fastest setup using PHP's built-in server:

# 1. Navigate to the application directory
cd fastway-app

# 2. Start PHP server
php -S localhost:8000

# 3. Open in browser
# http://localhost:8000

That's it! The application should now be running.

Detailed Installation

Prerequisites

Before installing, ensure you have:

  • PHP 7.4 or higher with the following extensions:

    • cURL
    • JSON
    • mbstring (usually included)

  • Web Server (one of):

    • Apache 2.4+
    • Nginx 1.18+
    • PHP Built-in Server (development only)

  • Modern Web Browser:

    • Chrome 90+
    • Firefox 88+
    • Safari 14+
    • Edge 90+

Method 1: PHP Built-in Server (Recommended for Development)

Advantages:

  • No configuration needed
  • Quick setup
  • Perfect for testing

Steps:

  1. Navigate to application directory:

    cd /path/to/fastway-app

  2. Start the server:

    php -S localhost:8000

    Or on a specific IP:

    php -S 0.0.0.0:8000  # Accessible from network

  3. Access the application:

    • Open browser: http://localhost:8000
    • Or: http://your-ip:8000

  4. Verify installation:

    • Visit: http://localhost:8000/system-check.php

Note: Press Ctrl+C to stop the server.

Method 2: Apache Server

Advantages:

  • Production-ready
  • Full .htaccess support
  • Better performance

Ubuntu/Debian Installation

  1. Install Apache and PHP:

    sudo apt update
sudo apt install apache2 php libapache2-mod-php php-curl php-json php-mbstring

  2. Enable required modules:

    sudo a2enmod rewrite
sudo a2enmod headers
sudo systemctl restart apache2

  3. Copy application to web root:

    sudo cp -r fastway-app /var/www/html/
sudo chown -R www-data:www-data /var/www/html/fastway-app

  4. Set permissions:

    cd /var/www/html/fastway-app
sudo mkdir -p logs
sudo chmod 755 logs
sudo chown www-data:www-data logs

  5. Configure Apache (Optional):

    Create virtual host: /etc/apache2/sites-available/fastway.conf

    <VirtualHost *:80>
    ServerName fastway.local
    DocumentRoot /var/www/html/fastway-app
    
    <Directory /var/www/html/fastway-app>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/fastway-error.log
    CustomLog ${APACHE_LOG_DIR}/fastway-access.log combined
</VirtualHost>

    Enable site:

    sudo a2ensite fastway.conf
sudo systemctl reload apache2

    Add to /etc/hosts:

    127.0.0.1 fastway.local

  6. Access application:

    • Default: http://localhost/fastway-app
    • Virtual host: http://fastway.local

CentOS/RHEL Installation

  1. Install Apache and PHP:

    sudo yum install httpd php php-curl php-json php-mbstring

  2. Start and enable Apache:

    sudo systemctl start httpd
sudo systemctl enable httpd

  3. Configure firewall:

    sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload

  4. Copy application:

    sudo cp -r fastway-app /var/www/html/
sudo chown -R apache:apache /var/www/html/fastway-app

  5. Set SELinux permissions (if enabled):

    sudo chcon -R -t httpd_sys_content_t /var/www/html/fastway-app
sudo chcon -R -t httpd_sys_rw_content_t /var/www/html/fastway-app/logs

  6. Access application:

    • http://server-ip/fastway-app

Method 3: Nginx Server

Advantages:

  • High performance
  • Low memory usage
  • Modern architecture

Installation Steps

  1. Install Nginx and PHP-FPM:

    sudo apt update
sudo apt install nginx php-fpm php-curl php-json php-mbstring

  2. Copy application:

    sudo cp -r fastway-app /var/www/
sudo chown -R www-data:www-data /var/www/fastway-app

  3. Configure Nginx:

    Create: /etc/nginx/sites-available/fastway

    server {
    listen 80;
    server_name fastway.local;
    root /var/www/fastway-app;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
    }
    
    location ~ /\.ht {
        deny all;
    }
    
    location /api/config.php {
        deny all;
    }
}

  4. Enable site:

    sudo ln -s /etc/nginx/sites-available/fastway /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

  5. Access application:

    • http://fastway.local

Post-Installation

1. Verify Installation

Visit the system check page:

http://your-url/system-check.php

This will verify:

  • PHP version
  • Required extensions
  • File permissions
  • Internet connectivity
  • Configuration files

2. Test Features

Test Tracking:

  1. Go to Track Parcel page
  2. Enter: Z60000983328
  3. Click "Track Parcel"
  4. Verify results appear

Test Quote:

  1. Go to Get Quote page
  2. Enter:
    • Suburb: Sandton
    • Postal Code: 2196
    • Weight: 2.5
    • Delivery Type: Express
  3. Click "Calculate Quote"
  4. Verify quote results appear

3. Configure for Production

Security Hardening:

  1. Disable debug mode: Edit api/track.php and api/quote.php:

    ini_set('display_errors', 0);

  2. Enable HTTPS: Uncomment in .htaccess:

    RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

  3. Restrict file access: Ensure .htaccess is active and working

  4. Set proper permissions:

    # Files should be readable, not writable by web server
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;

# Logs directory writable
chmod 755 logs

Troubleshooting Installation

Issue: "cURL not found"

Ubuntu/Debian:

sudo apt install php-curl
sudo systemctl restart apache2

CentOS/RHEL:

sudo yum install php-curl
sudo systemctl restart httpd

Issue: "Permission denied" errors

# Fix ownership
sudo chown -R www-data:www-data /var/www/html/fastway-app

# Fix permissions
sudo chmod -R 755 /var/www/html/fastway-app
sudo chmod -R 755 /var/www/html/fastway-app/logs

Issue: .htaccess not working

# Enable mod_rewrite
sudo a2enmod rewrite
sudo systemctl restart apache2

# Check Apache config allows .htaccess
# In /etc/apache2/sites-available/000-default.conf:
# AllowOverride All (not None)

Issue: 404 errors on pages

Check that mod_rewrite is enabled and .htaccess is being read:

sudo a2enmod rewrite
sudo systemctl restart apache2

Issue: Blank pages

Enable PHP error display temporarily:

# Add to php.ini
display_errors = On
error_reporting = E_ALL

# Restart web server
sudo systemctl restart apache2

Uninstallation

To remove the application:

# Stop web server (if using Apache)
sudo systemctl stop apache2

# Remove files
sudo rm -rf /var/www/html/fastway-app

# Remove virtual host (if created)
sudo rm /etc/apache2/sites-available/fastway.conf
sudo rm /etc/nginx/sites-available/fastway
sudo rm /etc/nginx/sites-enabled/fastway

# Restart web server
sudo systemctl start apache2
# or
sudo systemctl start nginx

Upgrading

To upgrade to a new version:

  1. Backup current installation:

    cp -r fastway-app fastway-app-backup

  2. Backup logs:

    cp -r fastway-app/logs logs-backup

  3. Extract new version:

    # Remove old files except logs
rm -rf fastway-app/!(logs)

# Copy new files
cp -r new-version/* fastway-app/

  4. Restore logs:

    cp -r logs-backup/* fastway-app/logs/

  5. Test: Visit system-check.php

Support

If you encounter issues:

  1. Check logs/error.log
  2. Visit system-check.php
  3. Review browser console (F12)
  4. Check web server error logs
  5. Refer to README.md and SOP.md

Installation guide last updated: January 2026