SurfSense - DEPRECATED

Status: Deprecated as of December 2025. Replaced by AnythingLLM.

Why We Moved Away

SurfSense was evaluated as a RAG (Retrieval-Augmented Generation) platform for self-hosted documentation search. After extensive testing, several critical issues made it unsuitable for production use:

Issues Encountered

1. Docker Image Authentication Bug (GitHub Issues #576, #474)
2. The all-in-one Docker image has broken authentication
3. TokenHandler component has empty useEffect - JWT token extraction code is missing
4. Users get "You are not authenticated" after successful OAuth callback

5. Bug has been open/reopened since late 2025

6. No Authentik/OIDC Support

7. Only supports Google OAuth (hardcoded)
8. Cannot integrate with existing Authentik SSO infrastructure

9. Would require maintaining separate auth for this one app

10. Build-Time Environment Variables

11. Next.js NEXT_PUBLIC_* variables are baked in at build time
12. All-in-one image has localhost:8000 hardcoded for API calls

13. Required extensive patching/sed scripts to work behind reverse proxy

14. Maturity Issues

15. Version 0.0.8 as of December 2025
16. All-in-one image is labeled as "for evaluation purposes only"
17. Separate frontend/backend images are more production-ready but more complex

Migration to AnythingLLM

AnythingLLM was chosen as the replacement because: - Header-based authentication support (works with Authentik forward auth) - More mature codebase with active development - Single Docker image that works properly - Multi-user support with workspace isolation - Supports llama.cpp backend for better performance

See AnythingLLM documentation for the current RAG platform setup.

---

Historical Reference

The following documents the original SurfSense deployment for reference only.

Original Architecture

┌────────────────────────────────────────────────────────────┐
│               LXC 180 (10.89.97.180)                       │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │     Docker: ghcr.io/modsetter/surfsense:latest       │  │
│  │                                                      │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐       │  │
│  │  │ Frontend │  │ Backend  │  │  PostgreSQL  │       │  │
│  │  │  :3000   │  │  :8000   │  │  + pgvector  │       │  │
│  │  └──────────┘  └──────────┘  └──────────────┘       │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

Original Configuration

• LXC 180: Stopped, container preserved for data recovery if needed
• Docker Compose: /opt/surfsense/docker-compose.yml (on LXC 180)
• K8s Resources: Deleted (external endpoint pattern was used)

Cleanup Performed

# K8s resources removed
kubectl delete ingress surfsense -n default
kubectl delete service surfsense surfsense-external -n default

# LXC container stopped
pct stop 180

# Manifests removed
rm -rf /root/tower-fleet/manifests/apps/surfsense/

Resources

• Original Source: https://github.com/MODSetter/SurfSense
• GitHub Issues: #576, #474 (authentication bugs)