Helpdesk Redis Issues

Why This Blog?

If you have encountered an "Internal Server Error" when using the search bar in the Helpdesk app, or if your search results simply never update, you are likely facing a Redis configuration bottleneck. This post provides a permanent fix by enabling specific Redis modules and automating the background indexing process.

In this article we’ll cover:

1. Configuring Redis Stack modules (rejson and redisearch)
2. Implementing automated indexing via DocEvents
3. Troubleshooting installation failures related to Redis ports
4. A quick-reference cheat sheet for terminal commands

---

1. Prerequisites – Required Modules

Before the Helpdesk search can function, the Redis server must be capable of handling JSON data and search queries.

Component	Required Module	Typical Path
ReJSON	rejson.so	/opt/redis-stack/lib/rejson.so
RediSearch	redisearch.so	/opt/redis-stack/lib/redisearch.so

---

2. Loading Redis Modules

Standard Redis instances often lack the full-text search capabilities required by the Helpdesk app. We must explicitly load these modules in the configuration.

1. Locate the redis_cache.config file in the config folder of your main bench directory.
2. Add the following lines to the bottom of the file:

loadmodule /opt/redis-stack/lib/rejson.so
loadmodule /opt/redis-stack/lib/redisearch.so

Note: Once saved, you must restart the bench instance to apply the changes.

---

3. Automating the Search Index

By default, the search index may require manual rebuilds. To ensure new articles are searchable immediately, we hook into the Frappe document lifecycle.

3.1 Update hooks.py

Navigate to apps/helpdesk/helpdesk/hooks.py and add the "HD Article" events to trigger the search build.

doc_events = {
    "HD Article": {
        "on_update": "helpdesk.utils.enqueue_search_build",
        "on_trash": "helpdesk.utils.enqueue_search_build",
    }
}

3.2 Implement Logic in utils.py

Open apps/helpdesk/helpdesk/utils.py and add the background worker logic. Using enqueue_after_commit=True ensures the index only updates after the database has successfully saved the record.

def enqueue_search_build(doc, method=None):
    # This pushes the task to the background worker
    # ONLY after the database has successfully saved the record
    frappe.enqueue(
        "helpdesk.search.build_index",
        now=frappe.flags.in_test, 
        enqueue_after_commit=True
    )

---

4. Troubleshooting: The Redis Port Pitfall

A common issue occurs during the initial installation command: bench --site [site_name] install-app helpdesk. If you receive a lengthy error message, the installer likely cannot communicate with Redis to build the initial search schema.

4.1 Verifying Redis Modules

Run the following command to see if Redis is actually running the required modules on the expected port:

# Check specific port (usually 6379)
redis-cli -p 6379 MODULE LIST

# Check default
redis-cli MODULE LIST

4.2 The Fix

If the list is empty or the connection fails, verify your common_site_config.json. For local development, ensure the ports match the default Redis port (6379):

{
 "redis_cache": "redis://localhost:6379",
 "redis_queue": "redis://localhost:6379",
 "redis_socketio": "redis://localhost:6379"
}

---

5. Common Issues & Quick Fixes

Symptom	Likely Cause	Quick Fix
Internal Server Error on search	Redis modules not loaded	Check redis_cache.config for loadmodule lines
New articles don't appear in search	Indexing is not automatic	Implement the hooks.py and utils.py changes
install-app fails with long error	Port mismatch in site config	Point redis_cache to localhost:6379 in common_site_config.json
Search results are outdated	Sync required	Run bench --site [site] execute helpdesk.search.build_index

---

6. TL;DR – Terminal Cheat-Sheet

# 1. Edit Redis Config
# Add modules to config/redis_cache.config

# 2. Rebuild index manually (if needed)
bench --site [site_name] execute helpdesk.search.build_index

# 3. Update Hooks and Utils
# (Refer to Section 3 for code snippets)

# 4. Finalize changes
bench migrate

# 5. Verify Redis Modules
redis-cli MODULE LIST

---

Wrap-Up

By properly loading the RediSearch and ReJSON modules and automating the index build through Frappe’s doc_events, you transform a fragile search feature into a stable service. This setup prevents installation failures and ensures users always find the latest documentation.

Happy coding!