5q12's Indexer - Configuration Reference
==========================================

Version: [1.1.12]
Updated: 2025-09-14

CONFIGURATION STRUCTURE
=======================

{
  "version": "string",
  "main": { /* core settings */ },
  "exclusions": { /* file indexing controls */ },
  "viewable_files": { /* file viewing controls */ }
}

VERSION
=======

Property: version
Type: String
Default: "1.1.10"
Purpose: Configuration version for automatic updates
Values: Semantic version string (e.g., "1.0", "1.1")
Note: Automatically managed by update system

MAIN SETTINGS
=============

Cache Type
----------
Property: main.cache_type
Type: String
Default: "sqlite"
Options:
  "sqlite" - High performance SQLite caching (requires php-sqlite3)
  "json" - Standard JSON file caching (universal compatibility)
Performance: SQLite provides 5-10x faster directory loading

Icon Type
---------
Property: main.icon_type
Type: String
Default: "default"
Options:
  "default" - Full icon library with type-specific icons
  "minimal" - Generic file/folder icons only
  "emoji" - Unicode emoji icons (file/folder symbols)
  "disabled" - No icons displayed
Bandwidth: Minimal/emoji reduce icon requests

Local Icons
-----------
Property: main.local_icons
Type: Boolean
Default: false
Purpose: Store icons locally instead of API URLs
Benefits: Faster loading, offline capability, reduced API dependency
Requirement: Additional disk space for icon storage

API Control
-----------
Property: main.disable_api
Type: Boolean
Default: false
Purpose: Disable all external API communication
Effect: Forces offline mode, downloads all resources locally
Use Case: Air-gapped environments, security compliance

Download Controls
-----------------
Property: main.disable_file_downloads
Type: Boolean
Default: false
Purpose: Remove "DL" buttons from file listings
Use Case: Read-only browsers, security restrictions

Property: main.disable_folder_downloads
Type: Boolean
Default: false
Purpose: Remove "ZIP" buttons from folder listings
Requirement: Requires php-zip extension when enabled

Display Controls
----------------
Property: main.index_hidden
Type: Boolean
Default: false
Purpose: Show files/folders starting with "." (dot)
Hidden Items: .htaccess, .env, .git/, .DS_Store, etc.
Security: Keep disabled in production environments

Property: main.index_all
Type: Boolean
Default: false
WARNING: Overrides ALL filtering when enabled
Effect: Shows .indexer_files/, security files, everything
Use Case: Debug mode only, never in production

Access Control
--------------
Property: main.deny_list
Type: String (comma-separated)
Default: ""
Purpose: Block specific files/folders from display
Patterns:
  "folder" - Exact folder name
  "folder*" - Folder and all contents
  "folder/*" - Folder contents recursively
  "folder/.ext*" - All files with extension in folder
  "file.ext" - Specific file
Example: "admin, logs, .git, config/secrets*, uploads/.exe*"

Property: main.allow_list
Type: String (comma-separated)
Default: ""
Purpose: Force inclusion, overrides deny_list and extension settings
Priority: Takes precedence over all other exclusions
Conflicts: Rules in both lists are ignored

EXCLUSIONS (FILE INDEXING)
===========================

Purpose: Control which file types appear in directory listings
Type: Boolean for each file extension
Default: Most common types enabled (true), security-sensitive disabled (false)

Programming Languages
---------------------
Enabled by Default:
  index_js, index_py, index_java, index_cpp, index_go, index_rb
  All major programming languages included

Disabled by Default:
  index_php - Server-side code (security consideration)

Documents & Media
-----------------
All Enabled by Default:
  Documents: index_txt, index_pdf, index_docx, index_xlsx
  Images: index_png, index_jpg, index_gif, index_svg
  Video: index_mp4, index_mkv, index_webm
  Audio: index_mp3, index_flac, index_aac

Archives & Executables
----------------------
Enabled by Default:
  Archives: index_zip, index_rar, index_7z, index_tar
  Executables: index_exe, index_iso

Security-Sensitive Files
------------------------
Disabled by Default:
  Keys: index_key, index_rsa, index_dsa, index_ecdsa
  Secrets: index_secret, index_passwd, index_shadow
  Certificates: index_jks, index_keystore, index_p12, index_pfx
  SSH: index_authorized_keys, index_known_hosts
Security: Keep these disabled unless specifically needed

Folder Indexing
---------------
Property: exclusions.index_folders
Type: Boolean
Default: true
Purpose: Control whether directories appear in listings
Note: Disabling prevents all folder navigation

VIEWABLE FILES (BROWSER DISPLAY)
=================================

Purpose: Control which files open in browser vs download
Type: Boolean for each file extension
Browser Compatibility: Depends on browser support for file types

Text & Code Files
-----------------
Enabled by Default:
  Text: view_txt, view_md, view_json, view_xml, view_csv
  Code: view_js, view_py, view_css, view_html, view_yml
  Config: view_conf, view_ini, view_env

Disabled by Default:
  view_php - Security: prevents source code exposure

Media Files
-----------
Enabled by Default:
  Images: view_png, view_jpg, view_gif, view_svg, view_webp
  Video: view_mp4, view_webm, view_mov (browser-supported formats)
  Audio: view_mp3, view_aac, view_ogg

Documents
---------
Enabled by Default:
  view_pdf - Universal browser support
  view_docx, view_xlsx - Modern browsers with plugins
Note: Office documents may download if browser lacks support

Binary & Executable Files
--------------------------
Disabled by Default:
  Executables: view_exe, view_dll, view_app
  Archives: view_zip, view_rar, view_7z
  System: view_iso, view_dmg, view_deb
Security: Keep disabled to prevent accidental execution

Security Files
--------------
Disabled by Default:
  Certificates: view_cert, view_crt, view_pem
  Keys: view_key, view_rsa, view_openssh
  System: view_passwd, view_shadow, view_sudoers

CONFIGURATION PATTERNS
=======================

High Security Environment
--------------------------
{
  "main": {
    "disable_api": true,
    "local_icons": true,
    "disable_file_downloads": true,
    "deny_list": "admin, logs, .git, .env*, config/secrets*"
  },
  "exclusions": {
    "index_php": false,
    "index_key": false
  },
  "viewable_files": {
    "view_php": false
  }
}

Development Environment
-----------------------
{
  "main": {
    "index_hidden": true,
    "allow_list": "src*, docs*, .gitignore"
  },
  "exclusions": {
    "index_php": true
  },
  "viewable_files": {
    "view_php": true
  }
}

Public File Server
-------------------
{
  "main": {
    "deny_list": "admin, private, system, .htaccess"
  },
  "exclusions": {
    "index_php": false,
    "index_exe": false
  }
}

Media Server
------------
{
  "main": {
    "deny_list": "system, config"
  },
  "exclusions": {
    "index_png": true,
    "index_mp4": true,
    "index_mp3": true,
    "index_pdf": true
  },
  "viewable_files": {
    "view_png": true,
    "view_mp4": true,
    "view_mp3": true
  }
}

PRIORITY RULES
==============

Access Control Priority:
1. Conflicting rules (same path in both lists) -> Both ignored
2. Allow list -> Overrides all other exclusions
3. Deny list -> Blocks access
4. Extension settings -> Default behavior
5. Hidden files -> Controlled by index_hidden
6. Index all -> Overrides everything when enabled

File Processing Order:
1. Security checks (path traversal protection)
2. Allow list verification
3. Deny list verification
4. Extension-based filtering
5. Hidden file filtering
6. Final display decision

PERFORMANCE CONSIDERATIONS
===========================

SQLite Cache:
- 5-10x faster than JSON caching
- Recommended for directories with 100+ files
- Requires php-sqlite3 extension

Local Icons:
- Reduces API requests
- Faster page loading
- Requires additional disk space (~50MB)

API Disable:
- Eliminates network dependencies
- Requires manual updates
- Downloads all resources locally

VALIDATION RULES
=================

JSON Syntax: Must be valid JSON format
Boolean Values: Use true/false, not strings
String Lists: Comma-separated, no trailing commas
Version Format: Semantic versioning (major.minor)
Extension Keys: Must match predefined mappings

UPDATE BEHAVIOR
===============

Automatic Updates:
- Checks API hourly for new versions
- Merges new settings with existing configuration
- Creates backup before changes
- Preserves user customizations

Manual Updates:
- Set disable_api: true to prevent automatic updates
- Backup configuration before manual changes
- Clear cache after major changes

TROUBLESHOOTING
===============

Config Not Applied: Check JSON syntax, clear cache
Performance Issues: Enable SQLite caching
Security Concerns: Review deny_list and sensitive file settings
Display Problems: Verify extension mappings and browser compatibility

FILE EXTENSIONS SUPPORTED
==========================

Total Extensions: 400+
Categories: Programming (50+), Documents (20+), Media (30+), 
           Archives (15+), System (100+), Security (25+)
Updates: New extensions added via API updates

FILES AND LOCATIONS
===================

Configuration File: .indexer_files/config.json
Reference File: .indexer_files/config-reference.txt
Backup Location: .indexer_files/config.json.backup.[timestamp]
Update Log: .indexer_files/config_updates.log

USAGE EXAMPLES
==============

View reference file:
  cat .indexer_files/config-reference.txt
  less .indexer_files/config-reference.txt
  nano .indexer_files/config-reference.txt

Edit configuration:
  nano .indexer_files/config.json
  vim .indexer_files/config.json

Validate configuration:
  php -r "json_decode(file_get_contents('.indexer_files/config.json')); echo 'Valid';"

Backup configuration:
  cp .indexer_files/config.json .indexer_files/config.json.manual

Clear cache:
  rm -rf .indexer_files/index_cache/*