# 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

# 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)
```bash
# 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
```bash
# 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
```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