Deploying Apaxy

Introduction

Apaxy is a customizable theme built to enhance the experience of browsing web directories. It uses Apache’s mod_autoindex module combined with CSS styling to transform the default, plain directory listing into a beautiful, user-friendly file browser.

Apaxy is perfect for:

File sharing servers - Share files with colleagues or the public with a polished interface
Media libraries - Browse music, video, and image collections with appropriate icons
Software distribution - Host downloads with a professional-looking directory
Documentation archives - Organize and present files in an intuitive manner
Development asset servers - Serve static files during development with style

Key Features

CSS Customization

Style your directory listing with custom CSS to match your brand

JavaScript Support

Add interactivity and dynamic features with JavaScript

Custom Icons

Over 200 file type icons included with support for custom icons

Gallery Mode

Built-in lightgallery.js integration for image browsing

Why Deploy Apaxy on Klutch.sh?

Deploying Apaxy on Klutch.sh provides several advantages:

Instant deployment - Push your configuration and files, and Apaxy is live in minutes
Persistent storage - Your shared files remain intact across deployments
Custom domains - Use your own domain for a professional file sharing URL
Automatic HTTPS - All connections are secured with SSL certificates
Scalable resources - Adjust compute resources based on traffic needs

Prerequisites

Before deploying Apaxy on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account
Basic familiarity with Docker and Apache configuration
Git installed on your local machine

Project Structure

Create a new directory for your Apaxy project with the following structure:

apaxy-server/
├── Dockerfile
├── apaxy/
│   ├── .htaccess
│   ├── header.html
│   ├── footer.html
│   └── theme/
│       ├── style.css
│       ├── apaxy.js
│       └── icons/
│           └── (icon files)
├── share/
│   └── (your files to share)
└── conf/
    └── httpd-custom.conf

Creating the Dockerfile

Klutch.sh automatically detects Dockerfiles in your repository’s root directory. Create a Dockerfile that sets up Apache with Apaxy:

# Build stage: Configure Apaxy
FROM bash AS builder

WORKDIR /app

# Clone Apaxy repository
RUN apk add --no-cache git && \
    git clone https://github.com/oupala/apaxy.git /app/apaxy-src

# Configure Apaxy for root path
WORKDIR /app/apaxy-src
RUN bash apaxy-configure.sh -w ""

# Production stage: Apache with Apaxy
FROM httpd:2.4-alpine

# Set labels
LABEL name="apaxy-server" \
      description="Apaxy directory listing theme on Apache" \
      maintainer="Your Name"

# Remove default index.html
RUN rm -f /usr/local/apache2/htdocs/index.html

# Enable .htaccess overrides for mod_autoindex
RUN sed -i '/<Directory "\/usr\/local\/apache2\/htdocs">/,/<\/Directory>/ s/AllowOverride None/AllowOverride Options Indexes FileInfo/' /usr/local/apache2/conf/httpd.conf

# Configure Apache to listen on port 8080
RUN sed -i 's/Listen 80/Listen 8080/g' /usr/local/apache2/conf/httpd.conf

# Enable required Apache modules
RUN sed -i 's/#LoadModule rewrite_module/LoadModule rewrite_module/' /usr/local/apache2/conf/httpd.conf && \
    sed -i 's/#LoadModule expires_module/LoadModule expires_module/' /usr/local/apache2/conf/httpd.conf && \
    sed -i 's/#LoadModule deflate_module/LoadModule deflate_module/' /usr/local/apache2/conf/httpd.conf

# Copy Apaxy files from builder
COPY --from=builder /app/apaxy-src/apaxy/ /usr/local/apache2/htdocs/

# Copy custom configuration if present
COPY conf/ /usr/local/apache2/conf/extra/

# Include custom configuration
RUN echo "Include conf/extra/httpd-custom.conf" >> /usr/local/apache2/conf/httpd.conf || true

# Create share directory for user files
RUN mkdir -p /usr/local/apache2/htdocs/share

# Set proper permissions
RUN chown -R www-data:www-data /usr/local/apache2/htdocs/ || \
    chown -R daemon:daemon /usr/local/apache2/htdocs/

EXPOSE 8080

CMD ["httpd-foreground"]

Apache Configuration

Create a custom Apache configuration file at conf/httpd-custom.conf:

# Custom Apache configuration for Apaxy

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

# Enable caching for static assets
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType image/png "access plus 1 month"
    ExpiresByType image/gif "access plus 1 month"
    ExpiresByType image/svg+xml "access plus 1 month"
    ExpiresByType text/css "access plus 1 week"
    ExpiresByType application/javascript "access plus 1 week"
</IfModule>

# Security headers
<IfModule mod_headers.c>
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-XSS-Protection "1; mode=block"
</IfModule>

# Directory listing configuration
<Directory "/usr/local/apache2/htdocs">
    Options +Indexes +FollowSymLinks
    AllowOverride Options Indexes FileInfo
    Require all granted

    # Custom index options
    IndexOptions FancyIndexing HTMLTable SuppressRules
    IndexOptions IconsAreLinks ScanHTMLTitles NameWidth=*
    IndexOptions DescriptionWidth=*
</Directory>

# Deny access to hidden files
<FilesMatch "^\.">
    Require all denied
</FilesMatch>

# Allow .htaccess
<Files ".htaccess">
    Require all denied
</Files>

# Server status (optional, for monitoring)
<Location "/server-status">
    SetHandler server-status
    Require local
</Location>

Customizing the Theme

Custom Header

Create a custom header.html file to add branding:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>File Browser</title>
    <link rel="stylesheet" href="/theme/style.css">
</head>
<body>
    <div id="wrapper">
        <header>
            <h1>📁 File Browser</h1>
            <p>Welcome to our file sharing server. Browse and download files below.</p>
        </header>
        <main>

Create a custom footer.html file:

        </main>
        <footer>
            <p>Powered by <a href="https://oupala.github.io/apaxy/" target="_blank">Apaxy</a> •
               Hosted on <a href="https://klutch.sh" target="_blank">Klutch.sh</a></p>
        </footer>
    </div>
    <script src="/theme/apaxy.js"></script>
</body>
</html>

Custom Stylesheet

Create or modify theme/style.css for custom styling:

/* Custom Apaxy Theme */
:root {
    --primary-color: #2563eb;
    --background-color: #f8fafc;
    --text-color: #1e293b;
    --border-color: #e2e8f0;
    --hover-color: #f1f5f9;
}

* {
    box-sizing: border-box;
}

body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    background-color: var(--background-color);
    color: var(--text-color);
    margin: 0;
    padding: 0;
    line-height: 1.6;
}

#wrapper {
    max-width: 1200px;
    margin: 0 auto;
    padding: 20px;
}

header {
    text-align: center;
    padding: 40px 20px;
    background: linear-gradient(135deg, var(--primary-color), #1d4ed8);
    color: white;
    border-radius: 12px;
    margin-bottom: 30px;
}

header h1 {
    margin: 0 0 10px;
    font-size: 2.5rem;
}

header p {
    margin: 0;
    opacity: 0.9;
}

/* Directory listing table */
table {
    width: 100%;
    border-collapse: collapse;
    background: white;
    border-radius: 8px;
    overflow: hidden;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

th, td {
    padding: 12px 16px;
    text-align: left;
    border-bottom: 1px solid var(--border-color);
}

th {
    background: var(--primary-color);
    color: white;
    font-weight: 600;
}

tr:hover {
    background: var(--hover-color);
}

a {
    color: var(--primary-color);
    text-decoration: none;
}

a:hover {
    text-decoration: underline;
}

/* Icons */
img[alt="[ICO]"],
img[alt="[PARENTDIR]"],
img[alt="[DIR]"] {
    width: 24px;
    height: 24px;
    vertical-align: middle;
    margin-right: 8px;
}

footer {
    text-align: center;
    padding: 30px;
    color: #64748b;
    font-size: 0.875rem;
}

footer a {
    color: var(--primary-color);
}

/* Responsive design */
@media (max-width: 768px) {
    header h1 {
        font-size: 1.75rem;
    }

    th, td {
        padding: 8px 12px;
    }

    /* Hide description on mobile */
    td:nth-child(4),
    th:nth-child(4) {
        display: none;
    }
}

Alternative Dockerfile (Simple Setup)

If you prefer a simpler setup using the official Apaxy repository directly:

# Simple Apaxy Dockerfile
FROM httpd:2.4-alpine

# Install git and bash
RUN apk add --no-cache git bash

# Clone Apaxy
RUN git clone https://github.com/oupala/apaxy.git /tmp/apaxy

# Configure Apaxy
WORKDIR /tmp/apaxy
RUN bash apaxy-configure.sh -w ""

# Copy configured Apaxy to Apache htdocs
RUN cp -r /tmp/apaxy/apaxy/* /usr/local/apache2/htdocs/

# Remove default index.html
RUN rm -f /usr/local/apache2/htdocs/index.html

# Enable .htaccess overrides
RUN sed -i '/<Directory "\/usr\/local\/apache2\/htdocs">/,/<\/Directory>/ s/AllowOverride None/AllowOverride Options Indexes FileInfo/' /usr/local/apache2/conf/httpd.conf

# Configure port 8080
RUN sed -i 's/Listen 80/Listen 8080/g' /usr/local/apache2/conf/httpd.conf

# Create share directory
RUN mkdir -p /usr/local/apache2/htdocs/share

# Clean up
RUN rm -rf /tmp/apaxy && apk del git

EXPOSE 8080

CMD ["httpd-foreground"]

Local Development

Test your Apaxy setup locally before deploying to Klutch.sh:

Using Docker Compose

Create a docker-compose.yml for local development:

version: '3.8'

services:
  apaxy:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '8080:8080'
    volumes:
      - ./share:/usr/local/apache2/htdocs/share
    restart: unless-stopped

Build and Run Locally

# Build the Docker image
docker build -t apaxy-server .

# Run the container
docker run -d -p 8080:8080 -v $(pwd)/share:/usr/local/apache2/htdocs/share apaxy-server

# Test the setup
curl http://localhost:8080/

Add some test files to the share directory:

# Create sample files
mkdir -p share/documents share/images share/downloads

# Add sample files
echo "Hello World" > share/documents/readme.txt
echo "# Sample Markdown" > share/documents/sample.md
touch share/downloads/app-v1.0.0.zip

Visit http://localhost:8080/share/ to see your themed directory listing.

Deploying to Klutch.sh

Push your code to GitHub

Initialize a Git repository and push to GitHub:

cd apaxy-server
git init
git add .
git commit -m "Initial Apaxy setup"
git remote add origin https://github.com/yourusername/apaxy-server.git
git push -u origin main

Create a new project on Klutch.sh
Navigate to klutch.sh/app and create a new project. Give your project a descriptive name like “apaxy-server” or “file-browser”.
Connect your GitHub repository
Select GitHub as your git source and authorize Klutch.sh to access your repositories. Select the repository containing your Apaxy project.
Configure the deployment
Klutch.sh will automatically detect your Dockerfile. Configure the following settings:
- Traffic Type: HTTP
- Internal Port: 8080
Add a persistent volume
To persist your shared files across deployments, add a persistent volume:
- Mount Path: /usr/local/apache2/htdocs/share
- Size: Choose based on your storage needs (e.g., 10 GB)
This ensures your uploaded files remain available even after redeployments.
Deploy your application
Click the deploy button to start the build process. Klutch.sh will:
1. Clone your repository
2. Build the Docker image
3. Deploy the container
4. Configure networking and SSL
Access your Apaxy instance
Once deployed, your Apaxy file browser will be available at:
```
https://your-app-name.klutch.sh
```
Your shared files will be accessible at:
```
https://your-app-name.klutch.sh/share/
```

Environment Variables

Apaxy itself doesn’t require environment variables, but you can configure Apache behavior:

Variable	Description	Default
`APACHE_LOG_DIR`	Directory for Apache logs	`/usr/local/apache2/logs`
`APACHE_RUN_USER`	User Apache runs as	`daemon`
`APACHE_RUN_GROUP`	Group Apache runs as	`daemon`

Enabling Gallery Mode

Apaxy includes built-in support for lightgallery.js for image browsing. To enable it:

Dockerfile Changes for Gallery Mode

# Add after copying Apaxy files
WORKDIR /usr/local/apache2/htdocs

# Enable gallery mode
RUN if [ -f header-lightgallery.html ]; then \
        mv header.html header-original.html && \
        mv header-lightgallery.html header.html && \
        mv footer.html footer-original.html && \
        mv footer-lightgallery.html footer.html; \
    fi

Gallery Usage

With gallery mode enabled, clicking on images in the directory listing will open them in a lightbox viewer with:

Slideshow functionality
Zoom controls
Fullscreen mode
Touch/swipe support on mobile

Adding Custom File Icons

Apaxy supports custom icons for different file types. To add icons for new file types:

1. Add the Icon File

Place your icon in the theme/icons/ directory:

theme/icons/
├── custom-type.png
└── your-extension.png

2. Update the .htaccess File

Add icon mappings to your .htaccess:

# Custom file type icons
AddIcon /theme/icons/custom-type.png .custom
AddIconByType (custom,/theme/icons/custom-type.png) application/x-custom

# Programming languages
AddIcon /theme/icons/typescript.png .ts .tsx
AddIcon /theme/icons/rust.png .rs
AddIcon /theme/icons/go.png .go

Password Protection

To add basic authentication to your file browser:

Update Apache Configuration

Add to conf/httpd-custom.conf:

# Enable auth modules
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authn_file_module modules/mod_authn_file.so

<Directory "/usr/local/apache2/htdocs/share/private">
    AuthType Basic
    AuthName "Private Files"
    AuthUserFile /usr/local/apache2/conf/.htpasswd
    Require valid-user
</Directory>

Dockerfile Changes for Authentication

# Create password file (replace 'admin' and 'password' with secure values)
RUN htpasswd -bc /usr/local/apache2/conf/.htpasswd admin password

Monitoring and Logs

Viewing Logs

Apache logs are stored in /usr/local/apache2/logs/. To persist logs, add a volume:

Mount Path: /usr/local/apache2/logs
Size: 1 GB

Log Format Customization

Add to your Apache configuration:

# Custom log format
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
CustomLog /usr/local/apache2/logs/access.log combined
ErrorLog /usr/local/apache2/logs/error.log
LogLevel warn

Custom Domain Setup

To use a custom domain with your Apaxy deployment:

Navigate to your project settings in the Klutch.sh dashboard
Add your custom domain (e.g., files.yourdomain.com)
Configure DNS by adding a CNAME record pointing to your Klutch.sh app URL
Wait for SSL provisioning - Klutch.sh automatically provisions SSL certificates

Troubleshooting

Common Issues

Problem: Getting a 403 Forbidden error when accessing directories.

Solution: Ensure .htaccess overrides are enabled:

<Directory "/usr/local/apache2/htdocs">
    AllowOverride Options Indexes FileInfo
    Options +Indexes
    Require all granted
</Directory>

Problem: File type icons are not displaying.

Solution: Check the icon paths in .htaccess:

# Paths should be relative to web root
AddIcon /theme/icons/pdf.png .pdf

Ensure icons exist in the correct location.

Problem: Custom CSS styles are not being applied.

Solution: Clear browser cache and verify the stylesheet path in header.html:

<link rel="stylesheet" href="/theme/style.css">

Problem: Cannot write to share directory.

Solution: Ensure proper permissions in the Dockerfile:

RUN chown -R daemon:daemon /usr/local/apache2/htdocs/share && \
    chmod -R 755 /usr/local/apache2/htdocs/share

Performance Optimization

Enable Compression