Cache Service Runbook

Overview

The Cache Service is a Node.js application that provides cached HTML content stored in PostgreSQL. It serves as a fallback mechanism for server-side rendered (SSR) content.

Prerequisites

System Requirements

• Node.js (version 12 or higher)
• PostgreSQL (version 12 or higher)
• npm (comes with Node.js)

Database Setup

1. Ensure PostgreSQL is running on localhost:5432
2. Create database and user:

   CREATE DATABASE gateway_cache;
   CREATE USER gateway WITH PASSWORD 'secret';
   GRANT ALL PRIVILEGES ON DATABASE gateway_cache TO gateway;
   

3. Create the required table:

   CREATE TABLE ssr_cache (
       id SERIAL PRIMARY KEY,
       route VARCHAR(255) NOT NULL,
       html TEXT NOT NULL,
       expiry TIMESTAMP WITH TIME ZONE NOT NULL,
       created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
   );
   

Installation & Startup

1. Clone/Setup Project

# Navigate to project directory
cd path/to/client-adapters

# Install dependencies
npm install

2. Start the Server

node server.js

Expected output:

✅ Database ready with 1 records
Server running on http://localhost:3000
Test with:
curl http://localhost:3000/test-db
curl http://localhost:3000/fallback/home

Testing & Verification

Health Check

# Test database connectivity
curl http://localhost:3000/test-db

Expected response: JSON array with cached records

Cache Endpoint Test

# Test cache retrieval
curl http://localhost:3000/fallback/home

Expected response: Cached HTML content or "No cached version"

Monitoring & Logs

Application Logs

• Database connection status is logged on startup
• Verification failures are logged with error messages
• Review console output for any errors or warnings

Database Monitoring

-- Check cache table contents
SELECT route, expiry, created_at FROM ssr_cache;

-- Check expired entries
SELECT * FROM ssr_cache WHERE expiry < NOW();

Troubleshooting

Common Issues

"Database verification failed"

• Cause: PostgreSQL not running or connection refused
• Solution:
  1. Check if PostgreSQL is running: systemctl status postgresql (Linux) or brew services list (Mac)
  2. Verify connection details in server.js
  3. Test database connection manually

"ssr_cache table not found"

• Cause: Database table hasn't been created
• Solution: Run the CREATE TABLE statement from Prerequisites section

"Cannot start server without valid database connection"

• Cause: Database verification failed
• Solution:
  1. Ensure database service is running
  2. Verify credentials (user: gateway, password: secret)
  3. Check if database 'gateway_cache' exists

Server doesn't start on port 3000

• Cause: Port already in use
• Solution:
  1. Check what's using port 3000: lsof -i :3000 (Unix) or netstat -ano | findstr :3000 (Windows)
  2. Either kill the process or modify the port in server.js

Debugging Steps

1. Check PostgreSQL is running and accessible
2. Verify database credentials and connection settings
3. Ensure the ssr_cache table exists and has data
4. Check server logs for specific error messages
5. Test database queries manually in psql

Maintenance

Regular Tasks

• Monitor disk space for PostgreSQL data directory
• Check for expired cache entries and clean up if needed
• Review server logs for any recurring errors
• Monitor memory usage of the Node.js process

Cache Management

-- Remove expired entries
DELETE FROM ssr_cache WHERE expiry < NOW();

-- View cache statistics
SELECT 
    COUNT(*) as total_entries,
    COUNT(*) FILTER (WHERE expiry > NOW()) as active_entries,
    COUNT(*) FILTER (WHERE expiry < NOW()) as expired_entries
FROM ssr_cache;

Service Management

Production Deployment

Consider using a process manager like PM2:

# Install PM2 globally
npm install -g pm2

# Start with PM2
pm2 start server.js --name cache-service

# Save PM2 configuration
pm2 save
pm2 startup

Environment Variables

For production, consider using environment variables:

const pool = new Pool({
    user: process.env.DB_USER || 'gateway',
    password: process.env.DB_PASSWORD || 'secret',
    host: process.env.DB_HOST || 'localhost',
    database: process.env.DB_NAME || 'gateway_cache',
    port: process.env.DB_PORT || 5432
});

Security Considerations

• Change default database password before production deployment
• Consider using connection pooling limits
• Implement proper logging for security events
• Use HTTPS in production environment