Linux-Server-Management-Toolkit/CACHE_MANAGEMENT.md

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

# 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 launcher.sh --clear-cache

Scenario 2: System Configuration Changed

# You added a new WordPress site
# You installed a new domain
# You created new databases
# But cache still shows old data

Solution:

bash launcher.sh --clear-cache
bash launcher.sh --detect-only    # Verify new config detected

Scenario 3: Moved Between Servers

# You cloned dev branch to a different server
# But cache contains data from the original server

Solution:

bash launcher.sh --clear-cache

---

Cache Commands

Clear All Cache

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 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

# 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

# See what's in the cache
cat .sysref.beta | head -20

# Count records by type
awk -F'|' '{print $1}' .sysref.beta | sort | uniq -c

# Count total lines (includes headers and all records)
wc -l .sysref.beta
# Note: This total includes system records, user records, headers, and blank lines
# NOT the count of WordPress sites

---

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

Fresh Deployment (First Clone or Migration)

# 1. Clone or navigate to toolkit directory
cd /root/server-toolkit-beta

# 2. Remove any old untracked files (including stale cache)
git clean -fd

# 3. Verify no cache files exist
ls -la .sysref* 2>&1

# 4. Run fresh - cache will be built automatically
bash launcher.sh --detect-only

After Git Pull

# 1. Update code from git
cd /root/server-toolkit-beta
git pull origin dev

# 2. Remove any untracked files from previous versions
git clean -fd

# 3. Verify detection works (cache auto-clears if launcher.sh changed)
bash launcher.sh --detect-only

# 4. Run normally
bash launcher.sh

After System Changes

# 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

# Just run normally - cache auto-expires after 1 hour
bash launcher.sh

---

Troubleshooting Cache Issues

Issue: Data Shows Stale Information

# 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

# Clear cache and rebuild
bash launcher.sh --clear-cache

# Check count
bash launcher.sh --detect-only | grep "WordPress"

Issue: User/Domain List is Old

# 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

# 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

# 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