454 lines
12 KiB
Markdown
454 lines
12 KiB
Markdown
# ZitiNexus Router Enrollment UI - Development Instructions
|
|
|
|
## ⚠️ CRITICAL: File Organization Rules
|
|
|
|
This document outlines **mandatory** development practices to prevent code duplication, maintain proper file organization, and ensure system stability. **Failure to follow these guidelines can break the entire UI system.**
|
|
|
|
---
|
|
|
|
## 1. STRICT FILE ORGANIZATION STRUCTURE
|
|
|
|
### 1.1 Directory Structure (MANDATORY)
|
|
|
|
```
|
|
UI/
|
|
├── public/ # ✅ PUBLIC FILES ONLY - Web server document root
|
|
│ ├── index.php # ✅ Login page (ONLY public-facing PHP file here)
|
|
│ ├── dashboard.php # ✅ Dashboard page (ONLY public-facing PHP file here)
|
|
│ └── assets/ # ✅ All static assets
|
|
│ ├── css/
|
|
│ │ └── style.css
|
|
│ ├── js/
|
|
│ │ └── app.js
|
|
│ └── images/
|
|
├── includes/ # ✅ BACKEND LOGIC ONLY - Never directly accessible
|
|
│ ├── config.php # ✅ Configuration and utilities
|
|
│ ├── auth.php # ✅ Authentication logic
|
|
│ ├── api_client.php # ✅ API communication
|
|
│ └── enrollment.php # ✅ Core enrollment logic
|
|
├── logs/ # ✅ Application logs
|
|
├── temp/ # ✅ Temporary files (if needed)
|
|
├── testfiles/ # ❌ REMOVE AFTER TESTING - Never in production
|
|
├── README.md # ✅ Documentation
|
|
├── INSTALLATION_GUIDE.md # ✅ Installation instructions
|
|
├── DEVELOPMENT_INSTRUCTIONS.md # ✅ This file
|
|
└── install.sh # ✅ Installation script
|
|
```
|
|
|
|
### 1.2 FORBIDDEN Practices
|
|
|
|
❌ **NEVER CREATE DUPLICATE PHP FILES**
|
|
- ❌ `UI/index.php` (root level) - REMOVE THIS
|
|
- ❌ `UI/dashboard.php` (root level) - REMOVE THIS
|
|
- ❌ `UI/testfiles/dashboard.php` - REMOVE AFTER TESTING
|
|
- ❌ Any PHP file outside `/public/` or `/includes/` directories
|
|
|
|
❌ **NEVER CREATE FILES IN WRONG LOCATIONS**
|
|
- ❌ Public-facing files outside `/public/`
|
|
- ❌ Backend logic files outside `/includes/`
|
|
- ❌ Assets outside `/public/assets/`
|
|
|
|
---
|
|
|
|
## 2. FILE CREATION GUIDELINES
|
|
|
|
### 2.1 Public-Facing PHP Files
|
|
|
|
**Location**: `/public/` directory ONLY
|
|
|
|
**Rules**:
|
|
- Must handle user interface and HTTP requests
|
|
- Must include authentication checks
|
|
- Must use relative paths for includes: `../includes/`
|
|
- Must use relative paths for assets: `assets/`
|
|
|
|
**Template for new public PHP files**:
|
|
```php
|
|
<?php
|
|
/**
|
|
* [File Description]
|
|
*/
|
|
|
|
// Include backend logic (ALWAYS relative from public directory)
|
|
require_once '../includes/auth.php';
|
|
require_once '../includes/config.php';
|
|
|
|
// Authentication check (MANDATORY for protected pages)
|
|
if (!isAuthenticated() || !isSessionValid()) {
|
|
header('Location: index.php?error=session_expired');
|
|
exit;
|
|
}
|
|
|
|
// Your page logic here...
|
|
?>
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title><?php echo APP_NAME; ?> - [Page Title]</title>
|
|
<!-- ALWAYS use relative paths for assets -->
|
|
<link rel="stylesheet" href="assets/css/style.css">
|
|
</head>
|
|
<body>
|
|
<!-- Your HTML here -->
|
|
<script src="assets/js/app.js"></script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### 2.2 Backend Logic Files
|
|
|
|
**Location**: `/includes/` directory ONLY
|
|
|
|
**Rules**:
|
|
- Must contain only PHP logic (no HTML output)
|
|
- Must be included by public files, never accessed directly
|
|
- Must use proper error handling and logging
|
|
|
|
**Template for new include files**:
|
|
```php
|
|
<?php
|
|
/**
|
|
* [File Description]
|
|
*
|
|
* This file contains backend logic and should never be accessed directly.
|
|
*/
|
|
|
|
// Prevent direct access
|
|
if (!defined('APP_NAME')) {
|
|
http_response_code(403);
|
|
exit('Direct access forbidden');
|
|
}
|
|
|
|
// Your backend logic here...
|
|
```
|
|
|
|
### 2.3 Asset Files
|
|
|
|
**Location**: `/public/assets/` directory structure
|
|
|
|
**Rules**:
|
|
- CSS files: `/public/assets/css/`
|
|
- JavaScript files: `/public/assets/js/`
|
|
- Images: `/public/assets/images/`
|
|
- Use relative paths in public PHP files: `assets/css/style.css`
|
|
|
|
---
|
|
|
|
## 3. INCLUDE PATH STANDARDS
|
|
|
|
### 3.1 From Public Directory Files
|
|
|
|
```php
|
|
// ✅ CORRECT - From /public/ files
|
|
require_once '../includes/config.php';
|
|
require_once '../includes/auth.php';
|
|
require_once '../includes/api_client.php';
|
|
require_once '../includes/enrollment.php';
|
|
```
|
|
|
|
### 3.2 From Include Files (Cross-includes)
|
|
|
|
```php
|
|
// ✅ CORRECT - From /includes/ files including other includes
|
|
require_once __DIR__ . '/config.php';
|
|
require_once __DIR__ . '/auth.php';
|
|
```
|
|
|
|
### 3.3 Asset Paths in Public Files
|
|
|
|
```php
|
|
// ✅ CORRECT - In public PHP files
|
|
<link rel="stylesheet" href="assets/css/style.css">
|
|
<script src="assets/js/app.js"></script>
|
|
<img src="assets/images/logo.png" alt="Logo">
|
|
```
|
|
|
|
---
|
|
|
|
## 4. TESTING AND DEVELOPMENT WORKFLOW
|
|
|
|
### 4.1 Development Testing
|
|
|
|
**For testing new features**:
|
|
|
|
1. ✅ Create test files in `/testfiles/` directory
|
|
2. ✅ Use clear naming: `test-[feature-name].php`
|
|
3. ✅ Document what you're testing
|
|
4. ✅ **ALWAYS CLEAN UP** after testing
|
|
|
|
### 4.2 Test File Cleanup (MANDATORY)
|
|
|
|
**Before committing code**:
|
|
```bash
|
|
# Remove all test files
|
|
rm -rf UI/testfiles/
|
|
|
|
# Remove any duplicate files
|
|
rm -f UI/index.php # Keep only public/index.php
|
|
rm -f UI/dashboard.php # Keep only public/dashboard.php
|
|
rm -f UI/debug-*.php # Remove debug files
|
|
```
|
|
|
|
### 4.3 Pre-Commit Checklist
|
|
|
|
- [ ] No duplicate PHP files exist
|
|
- [ ] All public files are in `/public/` directory
|
|
- [ ] All backend logic is in `/includes/` directory
|
|
- [ ] All assets are in `/public/assets/` structure
|
|
- [ ] Include paths are correct and relative
|
|
- [ ] Asset paths are relative from public directory
|
|
- [ ] Test files have been removed
|
|
- [ ] No debug files remain
|
|
|
|
---
|
|
|
|
## 5. WEB SERVER CONFIGURATION
|
|
|
|
### 5.1 Document Root Configuration
|
|
|
|
**MANDATORY**: Web server document root MUST point to `/public/` directory
|
|
|
|
**Apache Virtual Host**:
|
|
```apache
|
|
<VirtualHost *:80>
|
|
ServerName ziti-enrollment.local
|
|
DocumentRoot /var/www/ziti-enrollment/public # ← CRITICAL: Points to public/
|
|
|
|
<Directory /var/www/ziti-enrollment/public>
|
|
AllowOverride All
|
|
Require all granted
|
|
DirectoryIndex index.php
|
|
</Directory>
|
|
</VirtualHost>
|
|
```
|
|
|
|
**Nginx Configuration**:
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name ziti-enrollment.local;
|
|
root /var/www/ziti-enrollment/public; # ← CRITICAL: Points to public/
|
|
index index.php;
|
|
|
|
location / {
|
|
try_files $uri $uri/ /index.php?$query_string;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5.2 Security Benefits
|
|
|
|
This structure provides:
|
|
- ✅ Backend logic files are not directly accessible via web
|
|
- ✅ Configuration files are protected
|
|
- ✅ Only intended public files can be accessed
|
|
- ✅ Proper separation of concerns
|
|
|
|
---
|
|
|
|
## 6. CODE QUALITY STANDARDS
|
|
|
|
### 6.1 PHP Coding Standards
|
|
|
|
**File Headers**:
|
|
```php
|
|
<?php
|
|
/**
|
|
* [File Description]
|
|
*
|
|
* [Detailed description of file purpose]
|
|
*
|
|
* @author [Your Name]
|
|
* @version 1.0.0
|
|
*/
|
|
```
|
|
|
|
**Error Handling**:
|
|
```php
|
|
// ✅ ALWAYS use proper error handling
|
|
try {
|
|
// Your code here
|
|
} catch (Exception $e) {
|
|
logMessage('ERROR', 'Operation failed: ' . $e->getMessage());
|
|
// Handle error appropriately
|
|
}
|
|
```
|
|
|
|
**Input Sanitization**:
|
|
```php
|
|
// ✅ ALWAYS sanitize user input
|
|
$userInput = sanitizeInput($_POST['field'] ?? '');
|
|
```
|
|
|
|
### 6.2 Security Best Practices
|
|
|
|
**Authentication Checks**:
|
|
```php
|
|
// ✅ MANDATORY for all protected pages
|
|
if (!isAuthenticated() || !isSessionValid()) {
|
|
header('Location: index.php?error=session_expired');
|
|
exit;
|
|
}
|
|
```
|
|
|
|
**CSRF Protection**:
|
|
```php
|
|
// ✅ For all forms
|
|
<input type="hidden" name="csrf_token" value="<?php echo generateCSRFToken(); ?>">
|
|
|
|
// ✅ For form processing
|
|
if (!verifyCSRFToken($_POST['csrf_token'] ?? '')) {
|
|
http_response_code(403);
|
|
exit('CSRF token validation failed');
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. DEPLOYMENT GUIDELINES
|
|
|
|
### 7.1 Production Deployment Checklist
|
|
|
|
- [ ] Web server document root points to `/public/`
|
|
- [ ] No test files exist in production
|
|
- [ ] No duplicate files exist
|
|
- [ ] File permissions are correct (755 for directories, 644 for files)
|
|
- [ ] Log directories are writable (777 for `/logs/`)
|
|
- [ ] Default passwords have been changed
|
|
- [ ] Debug mode is disabled
|
|
|
|
### 7.2 File Permissions
|
|
|
|
```bash
|
|
# Set proper permissions
|
|
sudo chown -R www-data:www-data /var/www/ziti-enrollment
|
|
sudo chmod -R 755 /var/www/ziti-enrollment
|
|
sudo chmod -R 644 /var/www/ziti-enrollment/public/*.php
|
|
sudo chmod -R 644 /var/www/ziti-enrollment/includes/*.php
|
|
sudo chmod -R 777 /var/www/ziti-enrollment/logs
|
|
```
|
|
|
|
---
|
|
|
|
## 8. TROUBLESHOOTING FILE ORGANIZATION ISSUES
|
|
|
|
### 8.1 Common Problems and Solutions
|
|
|
|
**Problem**: "File not found" errors
|
|
**Cause**: Incorrect include paths or files in wrong locations
|
|
**Solution**: Verify file locations match this structure exactly
|
|
|
|
**Problem**: Assets not loading (CSS/JS)
|
|
**Cause**: Incorrect asset paths or document root misconfiguration
|
|
**Solution**: Use relative paths and ensure document root points to `/public/`
|
|
|
|
**Problem**: Duplicate functionality or conflicts
|
|
**Cause**: Multiple versions of the same file
|
|
**Solution**: Remove all duplicates, keep only files in correct locations
|
|
|
|
### 8.2 File Organization Audit Script
|
|
|
|
Create this script to check file organization:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# File: check-organization.sh
|
|
|
|
echo "=== ZitiNexus UI File Organization Audit ==="
|
|
|
|
# Check for duplicate PHP files
|
|
echo "Checking for duplicate PHP files..."
|
|
if [ -f "UI/index.php" ]; then
|
|
echo "❌ FOUND: UI/index.php (should be removed - use public/index.php)"
|
|
fi
|
|
|
|
if [ -f "UI/dashboard.php" ]; then
|
|
echo "❌ FOUND: UI/dashboard.php (should be removed - use public/dashboard.php)"
|
|
fi
|
|
|
|
if [ -d "UI/testfiles" ]; then
|
|
echo "❌ FOUND: UI/testfiles/ directory (should be removed in production)"
|
|
fi
|
|
|
|
# Check required structure
|
|
echo "Checking required directory structure..."
|
|
[ -d "UI/public" ] && echo "✅ UI/public/ exists" || echo "❌ UI/public/ missing"
|
|
[ -d "UI/includes" ] && echo "✅ UI/includes/ exists" || echo "❌ UI/includes/ missing"
|
|
[ -d "UI/public/assets" ] && echo "✅ UI/public/assets/ exists" || echo "❌ UI/public/assets/ missing"
|
|
|
|
echo "=== Audit Complete ==="
|
|
```
|
|
|
|
---
|
|
|
|
## 9. EMERGENCY RECOVERY PROCEDURES
|
|
|
|
### 9.1 If System Breaks Due to File Organization Issues
|
|
|
|
1. **Stop web server**:
|
|
```bash
|
|
sudo systemctl stop apache2 # or nginx
|
|
```
|
|
|
|
2. **Remove all duplicate files**:
|
|
```bash
|
|
rm -f UI/index.php
|
|
rm -f UI/dashboard.php
|
|
rm -rf UI/testfiles/
|
|
```
|
|
|
|
3. **Verify correct structure exists**:
|
|
```bash
|
|
ls -la UI/public/
|
|
ls -la UI/includes/
|
|
```
|
|
|
|
4. **Fix file permissions**:
|
|
```bash
|
|
sudo chown -R www-data:www-data /var/www/ziti-enrollment
|
|
sudo chmod -R 755 /var/www/ziti-enrollment
|
|
```
|
|
|
|
5. **Restart web server**:
|
|
```bash
|
|
sudo systemctl start apache2 # or nginx
|
|
```
|
|
|
|
### 9.2 Backup Strategy
|
|
|
|
**Before making changes**:
|
|
```bash
|
|
# Create backup
|
|
tar -czf ziti-ui-backup-$(date +%Y%m%d-%H%M%S).tar.gz UI/
|
|
|
|
# Test changes in development environment first
|
|
```
|
|
|
|
---
|
|
|
|
## 10. SUMMARY - GOLDEN RULES
|
|
|
|
### ✅ DO:
|
|
1. Keep all public PHP files in `/public/` directory
|
|
2. Keep all backend logic in `/includes/` directory
|
|
3. Use relative paths correctly based on file location
|
|
4. Clean up test files before committing
|
|
5. Follow the exact directory structure outlined
|
|
6. Test changes in development environment first
|
|
|
|
### ❌ DON'T:
|
|
1. Create duplicate PHP files
|
|
2. Put public files outside `/public/` directory
|
|
3. Put backend logic outside `/includes/` directory
|
|
4. Use absolute paths for includes or assets
|
|
5. Leave test files in production
|
|
6. Modify file organization without following these guidelines
|
|
|
|
---
|
|
|
|
**Remember**: The previous system breakage was caused by violating these file organization principles. Following these instructions religiously will prevent similar issues and maintain system stability.
|
|
|
|
**When in doubt**: Refer to this document and the existing working file structure. If you need to create new files, follow the templates and patterns established here.
|