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

Version: [2.0.0]
Updated: 2025-10-19

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

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

VERSION
=======

Property: version
Type: String
Purpose: Configuration version for automatic updates
Values: Semantic version string (e.g., "1.0", "1.1")
Note: Automatically updated independantly for both script and docker installations.

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

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

Access URL
----------
Property: main.access_url
Type: String
Default: ""
Purpose: Override automatic URL detection for share links
Use Case: Reverse proxy configurations, custom domains
Effect: When set, all share URLs use this base URL instead of auto-detected values
Format: Full URL with protocol (e.g., "https://file.example.com:8443")
Example: "https://file.example.com:8443"
Note: Leave empty ("") for automatic detection

Download Controls
-----------------
Property: main.disable_file_downloads
Type: Boolean
Default: false
Purpose: Removes the Download options from file action menus
Use Case: Read-only browsers, security restrictions

Property: main.disable_folder_downloads
Type: Boolean
Default: false
Purpose: Removes the Download options from folder action menus
Requirement: Requires php-zip extension when enabled

Property: main.max_download_size_file
Type: String
Default: "2048 MB"
Purpose: Set the max size for downloadable files using "value MB,GB,TB"
Use Case: Restrict the size for files available to download

Property: main.max_download_size_folder
Type: String
Default: "2048 MB"
Purpose: Set the max size for downloadable folders using "value MB,GB,TB"
Use Case: Restrict the size for folders available to download

Image Controls
-----------------
Property: main.disable_raw_image_conversion
Type: Boolean
Default: false
Purpose: Disable the live conversion of raw image formats using the Img.php image viewer
Use Case: Limit high intesive CPU image proccessing of raw image formats

Property: main.max_image_resolution
Type: String
Default: "3840x2160"
Purpose: Sets the max resolution for raw images that are converted using the Img.php image display 
Use Case: Limit high intesive CPU image proccessing of raw image formats

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_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
  }
}

Reverse Proxy Setup
--------------------
{
  "main": {
    "access_url": "https://file.example.com:8443"
  }
}

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

URL Generation Priority:
1. Custom access_url (when configured)
2. Automatic detection from HTTP headers

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

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

Access URL:
- No performance impact
- Prevents incorrect share URLs in reverse proxy setups
- Essential for proper functionality behind load balancers

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
Access URL Format: Must include protocol (http:// or https://)

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
Incorrect Share URLs: Set access_url for reverse proxy configurations
Share Links Not Working: Verify access_url includes protocol and port

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

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/*

Set reverse proxy URL:
  # Edit config.json and set:
  "access_url": "https://your-domain.com:port"