Add comprehensive cache management guide
DOCUMENTATION: - CACHE_MANAGEMENT.md: Complete cache management guide - Explains what gets cached and why - Shows how to clear stale cache - Provides troubleshooting for cache issues - Best practices for cache management CACHE COMMANDS: - bash launcher.sh --clear-cache (clear stale data) - bash launcher.sh --detect-only (verify fresh detection) CACHE LIFECYCLE: - First run: Builds cache from scratch - Subsequent runs: Uses cached data (fast) - After 1 hour: Cache auto-expires - On pull: Clear cache for fresh data SOLVES USER ISSUE: - Old WordPress site count (29 entries) - Stale domain/user listings - Data not refreshing after system changes - Cache files no longer committed to git
This commit is contained in:
Developer
@@ -0,0 +1,339 @@
|
||||
# Cache Management Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The Server Toolkit uses caching to avoid repeatedly scanning your system for:
|
||||
- WordPress installations
|
||||
- Database listings
|
||||
- User and domain information
|
||||
- System configuration
|
||||
- Firewall status
|
||||
|
||||
This document explains how caching works and how to manage it.
|
||||
|
||||
---
|
||||
|
||||
## Cache Basics
|
||||
|
||||
### What Gets Cached
|
||||
|
||||
The system maintains a **Reference Database** (`.sysref.beta`) containing:
|
||||
- **USER records** - All user accounts on server
|
||||
- **DOMAIN records** - All domains and their owners
|
||||
- **DB records** - All databases and their owners
|
||||
- **WP records** - All WordPress installations
|
||||
- **SYS records** - System configuration (detected once)
|
||||
- **HEALTH records** - Hardware baselines
|
||||
|
||||
### Cache Location
|
||||
|
||||
**Production:** `.sysref` (for `/root/server-toolkit/`)
|
||||
**Development:** `.sysref.beta` (for `/root/server-toolkit-beta/`)
|
||||
|
||||
Timestamps: `.sysref.timestamp` and `.sysref.beta.timestamp`
|
||||
|
||||
### Cache Lifetime
|
||||
|
||||
**TTL (Time To Live): 1 Hour**
|
||||
- Cache auto-rebuilds after 1 hour
|
||||
- Prevents stale data from being used too long
|
||||
- Balances performance vs. freshness
|
||||
|
||||
---
|
||||
|
||||
## Why You Need to Clear Cache
|
||||
|
||||
### Scenario 1: After Git Pull
|
||||
```bash
|
||||
# You pull the latest dev changes
|
||||
cd /root/server-toolkit-beta
|
||||
git pull origin dev
|
||||
|
||||
# But old cache is still present with stale data:
|
||||
# - 29 WordPress sites (from previous system)
|
||||
# - Old user list
|
||||
# - Outdated domain information
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
bash launcher.sh --clear-cache
|
||||
```
|
||||
|
||||
### Scenario 2: System Configuration Changed
|
||||
```bash
|
||||
# You added a new WordPress site
|
||||
# You installed a new domain
|
||||
# You created new databases
|
||||
# But cache still shows old data
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
bash launcher.sh --clear-cache
|
||||
bash launcher.sh --detect-only # Verify new config detected
|
||||
```
|
||||
|
||||
### Scenario 3: Moved Between Servers
|
||||
```bash
|
||||
# You cloned dev branch to a different server
|
||||
# But cache contains data from the original server
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
bash launcher.sh --clear-cache
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cache Commands
|
||||
|
||||
### Clear All Cache
|
||||
```bash
|
||||
bash launcher.sh --clear-cache
|
||||
```
|
||||
|
||||
Clears:
|
||||
- `.sysref.beta` and `.sysref.beta.timestamp`
|
||||
- All temporary files in `tmp/`
|
||||
- Next run will auto-rebuild cache
|
||||
|
||||
### Force Fresh Detection & Rebuild
|
||||
```bash
|
||||
bash launcher.sh --detect-only
|
||||
```
|
||||
|
||||
This command:
|
||||
1. Clears detection cache
|
||||
2. Re-detects system configuration
|
||||
3. Shows detected components
|
||||
4. Rebuilds reference database
|
||||
|
||||
### Check Cache Status
|
||||
```bash
|
||||
# See when cache was last built
|
||||
ls -la .sysref.beta*
|
||||
|
||||
# Check cache age
|
||||
stat .sysref.beta.timestamp
|
||||
|
||||
# See how much data is in cache
|
||||
wc -l .sysref.beta
|
||||
```
|
||||
|
||||
### View Cache Contents
|
||||
```bash
|
||||
# See what's in the cache
|
||||
cat .sysref.beta | head -20
|
||||
|
||||
# Count records by type
|
||||
awk -F'|' '{print $1}' .sysref.beta | sort | uniq -c
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatic Cache Behavior
|
||||
|
||||
### On First Run
|
||||
1. No cache exists
|
||||
2. System detection runs (httpd, MySQL, etc.)
|
||||
3. Reference database is built
|
||||
4. Cache is created: `.sysref.beta`
|
||||
5. Timestamp is recorded: `.sysref.beta.timestamp`
|
||||
|
||||
### On Subsequent Runs (Within 1 Hour)
|
||||
1. Cache exists and is fresh
|
||||
2. No detection runs (uses cached SYS_* variables)
|
||||
3. Reference database is read from cache
|
||||
4. Data is immediately available
|
||||
5. Menu opens instantly
|
||||
|
||||
### After 1 Hour
|
||||
1. Cache TTL expires
|
||||
2. Next run detects system changes
|
||||
3. Reference database is rebuilt
|
||||
4. New cache is written
|
||||
|
||||
---
|
||||
|
||||
## Git & Cache Interaction
|
||||
|
||||
### Problem: Cache Files in Git
|
||||
❌ **Before Fix:**
|
||||
```
|
||||
.sysref.beta <- COMMITTED TO GIT
|
||||
.sysref.beta.timestamp <- COMMITTED TO GIT
|
||||
data/*.dat <- COMMITTED TO GIT
|
||||
```
|
||||
|
||||
When you pulled, you got:
|
||||
- Old cache with 0 WordPress sites
|
||||
- Old database listings
|
||||
- Wrong data for your system
|
||||
|
||||
### Solution: Proper .gitignore
|
||||
✅ **After Fix:**
|
||||
```
|
||||
.gitignore includes:
|
||||
.sysref.beta ← NOT committed
|
||||
.sysref.beta.timestamp ← NOT committed
|
||||
/data/ ← NOT committed
|
||||
/tmp/ ← NOT committed
|
||||
/logs/ ← NOT committed
|
||||
```
|
||||
|
||||
Now when you pull:
|
||||
- No cache files are pulled
|
||||
- Fresh system detection runs
|
||||
- Your server's actual data is used
|
||||
|
||||
---
|
||||
|
||||
## Recommended Workflow
|
||||
|
||||
### After Git Pull
|
||||
```bash
|
||||
# 1. Update code from git
|
||||
cd /root/server-toolkit-beta
|
||||
git pull origin dev
|
||||
|
||||
# 2. Clear old cache
|
||||
bash launcher.sh --clear-cache
|
||||
|
||||
# 3. Verify detection works
|
||||
bash launcher.sh --detect-only
|
||||
|
||||
# 4. Run normally
|
||||
bash launcher.sh
|
||||
```
|
||||
|
||||
### After System Changes
|
||||
```bash
|
||||
# 1. Made changes (added domain, installed WordPress, etc.)
|
||||
|
||||
# 2. Clear cache
|
||||
bash launcher.sh --clear-cache
|
||||
|
||||
# 3. Verify changes are detected
|
||||
bash launcher.sh --detect-only
|
||||
|
||||
# 4. Run normally
|
||||
bash launcher.sh
|
||||
```
|
||||
|
||||
### Daily Operation
|
||||
```bash
|
||||
# Just run normally - cache auto-expires after 1 hour
|
||||
bash launcher.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Cache Issues
|
||||
|
||||
### Issue: Data Shows Stale Information
|
||||
```bash
|
||||
# Step 1: Clear cache
|
||||
bash launcher.sh --clear-cache
|
||||
|
||||
# Step 2: Verify fresh data
|
||||
bash launcher.sh --detect-only
|
||||
```
|
||||
|
||||
### Issue: WordPress Sites Count is Wrong
|
||||
```bash
|
||||
# Clear cache and rebuild
|
||||
bash launcher.sh --clear-cache
|
||||
|
||||
# Check count
|
||||
bash launcher.sh --detect-only | grep "WordPress"
|
||||
```
|
||||
|
||||
### Issue: User/Domain List is Old
|
||||
```bash
|
||||
# Force complete rebuild
|
||||
bash launcher.sh --clear-cache
|
||||
|
||||
# Wait for rebuild (takes a few seconds)
|
||||
# Then check:
|
||||
bash launcher.sh --detect-only
|
||||
```
|
||||
|
||||
### Issue: Cache File Corrupted
|
||||
```bash
|
||||
# Remove both cache files
|
||||
rm -f .sysref.beta .sysref.beta.timestamp
|
||||
|
||||
# Rebuild on next run
|
||||
bash launcher.sh --detect-only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cache Implementation Details
|
||||
|
||||
### How Cache Rebuilds
|
||||
|
||||
```bash
|
||||
# When cache is stale or missing:
|
||||
1. initialize_system_detection() # Detect httpd, MySQL, PHP, etc.
|
||||
2. db_ensure_fresh() # Check/rebuild reference database
|
||||
3. build_reference_database() # Scan for users, domains, WordPress
|
||||
4. Save to .sysref.beta # Write cache file
|
||||
5. Touch .sysref.beta.timestamp # Record timestamp
|
||||
```
|
||||
|
||||
Takes 3-10 seconds depending on:
|
||||
- Number of users
|
||||
- Number of domains
|
||||
- Number of WordPress installations
|
||||
- System I/O speed
|
||||
|
||||
### Cache Size
|
||||
|
||||
Typical cache sizes:
|
||||
- **10 users, 50 domains, 5 WP sites:** ~5 KB
|
||||
- **50 users, 500 domains, 50 WP sites:** ~50 KB
|
||||
- **500 users, 5000 domains, 500 WP sites:** ~500 KB
|
||||
|
||||
Cache is **text-based** for readability and easy debugging.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO
|
||||
|
||||
- Clear cache after system configuration changes
|
||||
- Clear cache after pulling git updates
|
||||
- Let cache auto-expire naturally (1 hour)
|
||||
- Use `--detect-only` to verify after clearing
|
||||
- Check cache age if data seems wrong
|
||||
|
||||
### ❌ DON'T
|
||||
|
||||
- Edit `.sysref.beta` manually (use clear instead)
|
||||
- Commit cache files to git (now impossible with .gitignore)
|
||||
- Rely on cache being more than 1 hour old
|
||||
- Delete cache during active operations
|
||||
- Copy cache between different servers (rebuild instead)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| **Clear all cache** | `bash launcher.sh --clear-cache` |
|
||||
| **Check detection** | `bash launcher.sh --detect-only` |
|
||||
| **See cache age** | `stat .sysref.beta.timestamp` |
|
||||
| **View cache contents** | `cat .sysref.beta` |
|
||||
| **Count cache entries** | `wc -l .sysref.beta` |
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-03-20
|
||||
**Cache Version:** 1.0
|
||||
**TTL:** 1 hour
|
||||
**Last Clear:** After git pull or major system changes
|
||||
Reference in New Issue
Block a user