Initial

2026-04-11 00:04:09 -05:00
commit 7a2fffd62e
110 changed files with 51809 additions and 0 deletions
@@ -0,0 +1,238 @@
+# 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:
+```bash
+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:
+```python
+SECRET_KEY = os.environ.get('SECRET_KEY') or 'your-production-secret-key-here'
+```
+
+For production, use environment variable or generate with:
+```python
+import secrets
+print(secrets.token_urlsafe(32))
+```
+
+#### **File Permissions**
+Set appropriate permissions on the server:
+```bash
+# 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:
+```bash
+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:
+```bash
+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**
+   ```bash
+   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**
+   ```bash
+   pip install -r app/requirements.txt
+   ```
+
+4. **Update Existing Users** (if applicable)
+   If you have existing users without the permission structure, add permissions:
+   ```json
+   {
+     "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**
+   ```bash
+   # 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