CGW-Quote-Builder/information/DEPLOYMENT_GUIDE.md

Deployment Guide - Files to Upload to Server

🚀 Updated Files for Login System & Permission System

To deploy the new login, location selection, user management, and permission system to your server, you'll need to upload the following files:

✅ Essential Updated Files

1. Main Application Files

These core files have been modified and MUST be uploaded:

• app/app.py - Main Flask application with authentication, sessions, and permissions
• app/config.py - Configuration (verify SECRET_KEY is set)
• app/requirements.txt - Python dependencies (may need to run pip install -r requirements.txt on server)

2. HTML Templates (all in app/templates/)

• app/templates/login.html - Login page
• app/templates/select_location.html - Location selection page (with User Management link)
• app/templates/user_manager.html - User management interface (with password change)
• app/templates/index2.html - Main app with user info header
• app/templates/access_denied.html - Permission denied page

3. CSS Files

• app/css/styles.css - Updated styles for user-info-bar and logout button

4. User Data

• app/data/users.json - User accounts with permissions
• app/data/example_user_structure.json - Example data format (documentation only)

⚠️ Important: If you have existing users on the server, back them up first, then merge the permission structure into existing user accounts.

📁 New Folders/Files Created

Admin Utilities (optional, but recommended)

• app/admin/ - New folder
• app/admin/README.md - Admin utilities documentation
• app/admin/fix_default_locations.py - User maintenance tool
• app/admin/test_password_security.py - Password security demo

⚠️ Security Note: The app/admin/ folder should NOT be web-accessible. Configure your server to block access to this directory.

📚 Documentation Files (moved to information/)

These files are for reference only and do NOT need to be uploaded to the production server:

• information/LOGIN_SYSTEM_README.md
• information/PERMISSIONS_SYSTEM.md
• information/PERMISSIONS_QUICKSTART.md
• information/USER_MANAGEMENT_README.md

🔧 Server Configuration

Python Dependencies

After uploading files, install/update dependencies on the server:

cd /path/to/app
pip install -r requirements.txt

Key dependencies (will be installed from requirements.txt):

• Flask >= 3.0.0
• Werkzeug (for password hashing)

Secret Key Configuration

Ensure app/config.py has a strong SECRET_KEY:

SECRET_KEY = os.environ.get('SECRET_KEY') or 'your-production-secret-key-here'

For production, use environment variable or generate with:

import secrets
print(secrets.token_urlsafe(32))

File Permissions

Set appropriate permissions on the server:

# Data directory should be writable by the web server
chmod 755 app/data/
chmod 644 app/data/users.json

# Admin directory should NOT be web accessible
chmod 700 app/admin/

WSGI Configuration

If using WSGI (Passenger, uWSGI, etc.):

• app/passenger_wsgi.py - Already exists (Passenger)
• app/wsgi.py - Already exists (generic WSGI)

Make sure your server is configured to use the appropriate WSGI file.

🔐 Security Checklist Before Deployment

• Change SECRET_KEY in config.py to a secure random value
• Verify users.json has ONLY hashed passwords (no plain text)
• Block web access to /app/admin/ directory
• Block web access to /app/data/ directory (except through API)
• Enable HTTPS/SSL on the server
• Set SESSION_COOKIE_SECURE = True in config.py if using HTTPS
• Set appropriate file permissions (755/644)
• Test login functionality after deployment
• Verify permissions system works (try accessing /users without permission)

📤 Upload Methods

Option 1: FTP/SFTP

Upload all the files listed above using your FTP client, maintaining the directory structure.

Option 2: Git

If using Git:

git add app/app.py app/templates/* app/css/* app/data/users.json app/admin/*
git commit -m "Add login system, permissions, and user management"
git push

Then on server:

git pull
pip install -r app/requirements.txt
# Restart web server

Option 3: ZIP Archive

Create a ZIP of the entire app/ folder and extract on the server.

🔄 Migration Steps for Existing Server

If you already have a running server:

1. Backup Current Installation

   cp -r app/ app_backup_$(date +%Y%m%d)/
   

2. Upload New Files Upload all files listed in "Essential Updated Files" section

3. Update Dependencies

   pip install -r app/requirements.txt
   

4. Update Existing Users (if applicable) If you have existing users without the permission structure, add permissions:

   {
     "username": "existing_user",
     "password": "existing_hash",
     "permissions": {
       "manage_users": false,
       "view_reports": true,
       "create_quotes": true
     }
   }
   

5. Test in Maintenance Mode

   • Test login at /login
   • Test user management at /users (as admin)
   • Test main app still works
   • Test permission checks

6. Restart Web Server

   # Apache with Passenger
   touch tmp/restart.txt
   
   # Or systemctl
   sudo systemctl restart your-service-name
   

🧪 Post-Deployment Testing

Test these flows after deployment:

1. Login Flow

   • Navigate to /login
   • Login with correct credentials
   • Verify redirect to location selection (if multiple locations)
   • Verify redirect to main app

2. Permission System

   • Login as admin user (Master)
   • Access /users - should work
   • Login as non-admin user
   • Try to access /users - should see "Access Denied"

3. Password Change

   • Login as admin
   • Go to User Management
   • Click "Change Password" on a user
   • Verify your password is required
   • Change password and verify new password works

4. Location Selection

   • Login as user with multiple locations
   • Verify location selection page shows
   • Verify User Management button shows only for admins
   • Select location and verify redirect to main app

❗ Troubleshooting

"500 Internal Server Error" after deployment:

• Check server error logs
• Verify SECRET_KEY is set
• Ensure all dependencies installed
• Check file permissions

"Users not loading" or "No users shown":

• Verify data/users.json uploaded correctly
• Check JSON format is valid
• Ensure web server can read the file

"Permission denied" when accessing files:

• Check file ownership (should be web server user)
• Set correct permissions (755 for directories, 644 for files)

Session not persisting:

• Verify SECRET_KEY is consistent
• Check cookie settings in config
• Ensure HTTPS if SESSION_COOKIE_SECURE is True

📞 Support

After deployment, keep these files handy:

• Server error logs (usually in /var/log/apache2/ or similar)
• information/LOGIN_SYSTEM_README.md - Login system documentation
• information/PERMISSIONS_SYSTEM.md - Permission system documentation

🎉 Success Indicators

You'll know deployment was successful when:

• ✅ Accessing / redirects to /login (if not logged in)
• ✅ Login with correct credentials works
• ✅ Master user can access /users
• ✅ Non-admin users see "Access Denied" at /users
• ✅ User info header shows in main app
• ✅ Logout works and redirects to login
• ✅ Password change requires admin verification