================================================================================ LOGISTICSPRO COMS - PRODUCTION DEPLOYMENT GUIDE Version: v1.2.0 | Last Updated: 04 Aug 2026 Target URL: https://courier.shakherhat.com/ ================================================================================ This guide provides step-by-step instructions to deploy LogisticsPro-COMS v1.2.0 to your production server. -------------------------------------------------------------------------------- 1. REQUIRED .ENV VARIABLES -------------------------------------------------------------------------------- Create or update your production `.env` file on the server with the following settings: # Application Configuration APP_URL=https://courier.shakherhat.com PORT=3000 NODE_ENV=production APP_DEBUG=false # MySQL Database Credentials (Aizoshop / Shakherhat DB) DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=shakherhat_shop DB_USERNAME=your_production_db_user DB_PASSWORD=your_production_db_password # Pathao Courier API Credentials (Live) PATHAO_BASE_URL=https://api-hermes.pathao.com PATHAO_CLIENT_ID=your_pathao_client_id PATHAO_SECRET_KEY=your_pathao_secret_key PATHAO_USERNAME=your_pathao_email PATHAO_PASSWORD=your_pathao_password PATHAO_STORE_ID=your_pathao_store_id # Pathao Courier API Credentials (Sandbox / Testing) PATHAO_IS_SANDBOX=false PATHAO_SANDBOX_BASE_URL=https://courier-api-sandbox.pathao.com PATHAO_SANDBOX_CLIENT_ID=your_sandbox_client_id PATHAO_SANDBOX_SECRET_KEY=your_sandbox_secret_key PATHAO_SANDBOX_USERNAME=your_sandbox_email PATHAO_SANDBOX_PASSWORD=your_sandbox_password PATHAO_SANDBOX_STORE_ID=your_sandbox_store_id # AI Integration GEMINI_API_KEY=your_gemini_api_key -------------------------------------------------------------------------------- 2. SERVER REQUIREMENTS -------------------------------------------------------------------------------- - Operating System: Ubuntu 22.04 LTS / Debian 11/12 or similar Linux OS - Memory: Minimum 1GB RAM (2GB+ recommended) - Disk Space: 5GB+ SSD - Web Server: Nginx (recommended) or Apache with Reverse Proxy -------------------------------------------------------------------------------- 3. NODE VERSION & TOOLING -------------------------------------------------------------------------------- - Node.js: v18.x or v20.x LTS (Recommended: v20.11.0+) - npm: v9.x or v10.x - Process Manager: PM2 (`npm install -g pm2`) -------------------------------------------------------------------------------- 4. NPM DEPENDENCIES -------------------------------------------------------------------------------- Install clean production dependencies: npm ci --only=production -------------------------------------------------------------------------------- 5. BUILD COMMANDS -------------------------------------------------------------------------------- Compile frontend assets and Node server bundle: npm run build This creates: - `dist/index.html` and static assets (Frontend SPA Bundle) - `dist/server.cjs` (Production Node Express Server Bundle) -------------------------------------------------------------------------------- 6. DATABASE SCHEMAS & MIGRATIONS -------------------------------------------------------------------------------- - MySQL (`shakherhat_shop`): - Requires existing tables: `orders`, `order_details`, `users`, `uploads`. - Automatically queries `uploads` table using `users.avatar_original` to serve user avatars (`https://shakherhat.com/public/{file_name}`). - SQLite (`pathao_logs.sqlite`): - Automatically initialized on server launch. - Contains tables: `pathao_api_logs`, `pathao_credentials`, `app_settings`, `theme_settings`, `sessions`. - Automatically migrates theme color columns and seeds default settings. -------------------------------------------------------------------------------- 7. STORAGE & PERMISSIONS SETUP -------------------------------------------------------------------------------- Ensure SQLite database file and application directory are writable by web process: touch pathao_logs.sqlite chmod 664 pathao_logs.sqlite Set appropriate ownership on server folder: sudo chown -R www-data:www-data /var/www/LogisticsPro-COMS chmod -R 755 /var/www/LogisticsPro-COMS chmod -R 775 /var/www/LogisticsPro-COMS/pathao_logs.sqlite -------------------------------------------------------------------------------- 8. CACHE & CLEAN COMMANDS -------------------------------------------------------------------------------- Clear stale build artifacts before starting: npm run clean -------------------------------------------------------------------------------- 9. PM2 PROCESS MANAGEMENT -------------------------------------------------------------------------------- Launch and keep the production server running using PM2: pm2 start dist/server.cjs --name "logistics-pro" pm2 save pm2 startup To restart the application process: pm2 restart logistics-pro To view application logs: pm2 logs logistics-pro -------------------------------------------------------------------------------- 10. CRON JOB CONFIGURATION -------------------------------------------------------------------------------- To run automatic background syncs for pending Pathao orders every 15 minutes, add to crontab (`crontab -e`): */15 * * * * curl -X POST https://courier.shakherhat.com/api/orders/sync-all > /dev/null 2>&1 -------------------------------------------------------------------------------- 11. SSL CERTIFICATE REQUIREMENTS -------------------------------------------------------------------------------- Install SSL certificate using Let's Encrypt / Certbot: sudo apt update sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d courier.shakherhat.com -------------------------------------------------------------------------------- 12. NGINX REVERSE PROXY CONFIGURATION -------------------------------------------------------------------------------- Nginx Configuration (`/etc/nginx/sites-available/courier.shakherhat.com`): server { listen 80; server_name courier.shakherhat.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name courier.shakherhat.com; ssl_certificate /etc/letsencrypt/live/courier.shakherhat.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/courier.shakherhat.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } -------------------------------------------------------------------------------- 13. FEATURE IMPLEMENTATION STATUS (v1.2.0) -------------------------------------------------------------------------------- [✓] Dark/Light Mode Theme Switching & SQLite + LocalStorage Persistence. [✓] Live Pathao Status Auto-Rule: "Return" status + "paid" payment updates Pathao status to "Paid Return" and payment status to "Unpaid". [✓] Dashboard Status Distribution Chart (Success, Pending, Cancel counts with HSL/Tailwind status colors). [✓] Dynamic Header Current Page Title (Dashboard, Orders, Settings). [✓] Sidebar Software Version (v1.2.0) & Last Update Date (04 Aug 2026). [✓] User Avatar Integration (queries `uploads` table via `users.avatar_original` ID with `https://shakherhat.com/public/` prefix). -------------------------------------------------------------------------------- 14. PRODUCTION SECURITY CHECKLIST -------------------------------------------------------------------------------- [✓] Ensure `.env` is listed in `.gitignore` and not committed to git repository. [✓] Ensure `APP_DEBUG=false` in production environment. [✓] Set strong MySQL password for database user. [✓] Never expose database credentials or secret keys in frontend code. [✓] Enable HTTPS/SSL encryption for all HTTP traffic. [✓] Restrict SSH access to authorized IP addresses. -------------------------------------------------------------------------------- 15. BACKUP RECOMMENDATION -------------------------------------------------------------------------------- 1. MySQL Database Backup: mysqldump -u root -p shakherhat_shop > /backups/shakherhat_shop_$(date +%F).sql 2. SQLite Settings & Logs Backup: cp pathao_logs.sqlite /backups/pathao_logs_$(date +%F).sqlite 3. Environment Configuration Backup: cp .env /backups/.env.production.bak -------------------------------------------------------------------------------- 16. ROLLBACK PROCEDURE -------------------------------------------------------------------------------- If an issue occurs after deployment: 1. Revert repository to previous stable git commit: git checkout 2. Rebuild assets: npm run build 3. Restart process with PM2: pm2 restart logistics-pro -------------------------------------------------------------------------------- 17. POST-DEPLOYMENT VERIFICATION CHECKLIST -------------------------------------------------------------------------------- [ ] Visit https://courier.shakherhat.com/ and test login/dashboard access. [ ] Check order listing page loads real database orders. [ ] Test Pathao Status Sync / Consignment tracking. [ ] Test Theme Switcher (Dark/Light mode) & confirm settings save into SQLite. [ ] Open Developer Tools (F12) to verify no console errors or network 500s. ================================================================================