Installation Guide

Table of Contents

• Quick Start
• System Requirements
• Installation Methods
• Web Server Configuration
• Initial Setup
• Troubleshooting Installation
• Performance Optimization

Quick Start

Basic Installation (5 minutes)

1. Download the indexer

wget https://github.com/5q12-ccls/5q12-s-Indexer/raw/main/index.php
   # or download manually from GitHub

1. Place in web directory

# Copy to your web root
   cp index.php /var/www/html/files/

1. Set permissions

chmod 644 index.php

1. Access in browser

https://yourdomain.com/files/

The indexer will automatically initialize and create necessary directories.

System Requirements

Minimum Requirements

Component	Requirement
PHP	7.0+
Web Server	Apache, Nginx, IIS, or any PHP-compatible server
Memory	64MB PHP memory limit
Disk Space	50MB for cache and temporary files
Extensions	json (usually enabled by default)

Recommended Requirements

Component	Requirement	Benefit
PHP	8.0+	Better performance and security
Memory	128MB+	Handle large directories efficiently
Disk Space	200MB+	Optimal caching and icon storage
SQLite3	Extension enabled	5-10x faster caching
ZipArchive	Extension enabled	Folder download functionality

Required PHP Extensions

Core Extensions (Usually Enabled)

• json - Configuration file handling
• curl or allow_url_fopen - API communication

Optional Extensions

• sqlite3 - High-performance caching (highly recommended)
• zip - Folder download as ZIP archives
• gd or imagick - Enhanced icon handling

Checking Your Environment

Check PHP version:

php --version

Check available extensions:

php -m | grep -E "(sqlite|zip|json|curl)"

Check PHP configuration:

<?php phpinfo(); ?>

Installation Methods

Method 1: Single File Deployment (Recommended)

Best for: Simple setups, shared hosting, quick deployment

1. Download index.php
2. Upload to desired directory
3. Access via web browser
4. Automatic configuration download

Pros:

• Simplest installation
• Automatic updates
• No manual configuration needed

Cons:

• Requires internet connection for initial setup
• API dependency for updates

Method 2: Offline Installation

Best for: Air-gapped networks, high-security environments

1. Download complete package including:

• index.php
• config.json
• extensionMap.json
• icons.json
• Icon files
• CSS files

1. Set "disable_api": true in configuration

Pros:

• No internet dependency
• Full offline operation
• Enhanced security

Cons:

• Manual updates required
• Larger initial download

Method 3: Development Setup

Best for: Customization, development, testing

# Clone repository
git clone https://github.com/user/repo.git
cd repo

# Copy to web directory
cp index.php /var/www/html/dev/

# Set development configuration
echo '{"main":{"disable_api":true,"index_hidden":true}}' > .indexer_files/config.json

Web Server Configuration

Apache Configuration

Basic .htaccess example:

# Allow indexer execution
<Files "index.php">
    Require all granted
</Files>

# Optional: Hide sensitive files
<Files "config.json">
    Require all denied
</Files>

# Optional: Custom error handling
ErrorDocument 404 /index.php

Virtual host example:

<VirtualHost *:80>
    ServerName files.yourdomain.com
    DocumentRoot /var/www/html/files
    
    <Directory "/var/www/html/files">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx Configuration

Basic server block:

server {
    listen 80;
    server_name files.yourdomain.com;
    root /var/www/html/files;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Security: Hide sensitive files
    location ~ /\.(indexer_files|git|env) {
        deny all;
    }
}

IIS Configuration (Windows)

web.config example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <defaultDocument>
            <files>
                <clear />
                <add value="index.php" />
            </files>
        </defaultDocument>
        
        <rewrite>
            <rules>
                <rule name="Indexer" stopProcessing="true">
                    <match url=".*" />
                    <conditions>
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                        <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="index.php" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

Initial Setup

Automatic Setup (Default)

When you first access the indexer:

1. Directory Creation

.indexer_files/
   ├── config.json
   ├── zip_cache/
   ├── index_cache/
   ├── icons/ (if local_icons enabled)
   └── local_api/ (if disable_api enabled)

1. Configuration Download

• Latest configuration from API
• Extension mappings
• Icon mappings

1. Cache Initialization

• SQLite database creation (if supported)
• Initial directory scanning

Manual Setup

If automatic setup fails:

# Create directory structure
mkdir -p .indexer_files/{zip_cache,index_cache,icons,local_api}

# Set permissions
chmod 755 .indexer_files
chmod 755 .indexer_files/*

# Create basic configuration
cat > .indexer_files/config.json << 'EOF'
{
  "version": "1.0",
  "main": {
    "cache_type": "json",
    "disable_api": false
  },
  "exclusions": {
    "index_folders": true,
    "index_txt": true
  },
  "viewable_files": {
    "view_txt": true
  }
}
EOF

Verification Steps

1. Check file permissions:

ls -la index.php .indexer_files/

1. Test web access:

curl -I https://yourdomain.com/path/to/indexer/

1. Verify configuration:

cat .indexer_files/config.json | python -m json.tool

Troubleshooting Installation

Common Issues

Permission Denied Errors

# Fix file permissions
chmod 644 index.php
chmod -R 755 .indexer_files/

# Fix ownership (Linux/Unix)
chown -R www-data:www-data .indexer_files/

PHP Extension Missing

# Ubuntu/Debian
sudo apt-get install php-sqlite3 php-zip

# CentOS/RHEL
sudo yum install php-sqlite3 php-zip

# Or compile with extensions
./configure --with-sqlite3 --with-zip

White Screen/No Output

1. Check PHP error logs
2. Enable error reporting temporarily:

<?php
   error_reporting(E_ALL);
   ini_set('display_errors', 1);
   ?>

API Connection Failures

1. Test connectivity:

curl -I https://api.indexer.ccls.icu

1. Enable offline mode:

{"main": {"disable_api": true}}

1. Check firewall rules:

# Allow outbound HTTPS
   ufw allow out 443

Debug Information

Collect system info:

php --version
php -m
uname -a
df -h
ls -la .indexer_files/

Check error logs:

tail -f /var/log/apache2/error.log
tail -f /var/log/nginx/error.log
tail -f .indexer_files/debug.log

Performance Optimization

PHP Configuration

Optimize php.ini:

; Memory and execution
memory_limit = 256M
max_execution_time = 60

; File uploads (for large files)
post_max_size = 100M
upload_max_filesize = 100M

; OPcache (recommended)
opcache.enable = 1
opcache.memory_consumption = 128
opcache.max_accelerated_files = 4000

Indexer Configuration

High-performance settings:

{
  "main": {
    "cache_type": "sqlite",
    "local_icons": true
  }
}

Web Server Optimization

Apache (.htaccess):

# Enable compression
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/css text/javascript application/javascript
</IfModule>

# Enable caching
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType image/png "access plus 1 month"
    ExpiresByType text/css "access plus 1 week"
</IfModule>

Nginx:

# Enable gzip compression
gzip on;
gzip_types text/css application/javascript image/png;

# Enable caching
location ~* \.(png|css|js)$ {
    expires 1M;
    add_header Cache-Control "public, immutable";
}

---

Next Steps: After installation, see the Configuration Guide to customize your indexer settings.