# 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