humbertovarona/webfileexplorer repository overview

⁠Web File Explorer Docker

A lightweight web-based file explorer that can be run as a Docker container with automatic SSL support.

⁠Functionalities

This document outlines the features of the simple web-based file explorer application. The application is built using only HTML, CSS, and JavaScript, and it visualizes the structure of a data/ directory served via HTTP.

⁠Core Functionalities

1. File and Folder Tree View:

   • Displays a hierarchical (tree-like) structure of files and folders mirroring the contents of a server-side data/ directory.
   • The structure is fetched from a data/data.json file.

2. Navigation:

   • Expand/Collapse Folders: Users can click on a folder's chevron icon or the folder entry (icon/name area) to expand or collapse its contents, revealing or hiding sub-folders and files. The expansion state of folders is remembered during the session across re-renders (e.g., after sorting or clearing search).
   • Direct Folder Navigation: Clicking on a folder's name (not the chevron/icon area) navigates into that folder, making it the current view.
   • Breadcrumb Navigation: A breadcrumb trail (e.g., data > documents > reports) is displayed above the file tree, showing the current path. Each segment of the breadcrumb is clickable, allowing users to quickly navigate back to parent directories.

3. Item Details Display:

   • Files:
     • Name: The filename.
     • Extension: The file extension (e.g., .pdf, .txt).
     • Size: File size, intelligently formatted (e.g., Bytes, KB, MB, GB). Handles sizes provided as raw bytes (numbers) or pre-formatted strings (e.g., "10.5 KB") in data.json.
     • Last Modified Date: (Optional, if provided in data.json) The date and time the file was last modified, displayed in a user-friendly format.
   • Folders:
     • Name: The folder name.
     • Item Count: (Optional) The number of direct children (files/folders) within that folder.

4. Iconography:

   • Type-Specific Icons: Files are represented by icons corresponding to their extension (e.g., PDF icon for .pdf, image icon for .jpg, Word icon for .docx). Folders have distinct open and closed folder icons.
   • Local SVG Icons: Icons are served locally from an icons/ (or libs/fontawesome/svgs/) directory, populated by a helper script (get_icons.sh).
   • Chevron icons are used for expand/collapse toggles.

5. File Access:

   • Clicking on a file name will attempt to open it in a new browser tab (if the browser supports the file type, e.g., images, PDFs, text files) or initiate a download.
   • File paths are constructed relative to the data/ directory.

6. Search Functionality:

   • A search input allows users to filter the displayed files and folders by typing a sub-string of their names.
   • Search results highlight the matching part of the name.
   • Parent folders of matching items are automatically expanded to make the results visible.
   • A "Clear search" button is available.

7. Sorting Options:

   • Users can sort the currently displayed list of files and folders by:
     • Name (alphabetical, ascending/descending)
     • Date (last modified, newest/oldest)
     • Type (extension for files, folders grouped first, then by extension)
     • Size (largest/smallest, for files)
   • The current sort criteria and direction are indicated in the UI.
   • Clicking an active sort button toggles the sort direction.

⁠User Interface (UI) and Experience (UX) Enhancements

1. Theming (Light/Dark Mode):

   • A toggle button allows users to switch between a light and a dark theme for the entire application, including the navbar.
   • Theme preference is saved in localStorage and applied on subsequent visits.

2. Font Size Adjustment:

   • Buttons are provided to increase or decrease the base font size of the application, improving readability.
   • Font size preference is saved in localStorage.

3. Responsive Design:

   • The interface is designed to be responsive and adapt to different screen sizes, utilizing Bootstrap's grid system and fluid containers. The file explorer tree view will use the available width.

4. Sticky Footer:

   • The footer remains at the bottom of the viewport on pages with short content, and below the content on pages that scroll.

5. Expand/Collapse All:

   • Buttons in the navbar allow users to expand all currently visible nested folders or collapse all of them with a single click.

6. Context Menu (Right-Click):

   • Right-clicking on a file or folder item brings up a custom context menu.
   • Options:
     • Open / Download: Same action as a left-click.
     • Preview:
       • For common image types (PNG, JPG, GIF, SVG, BMP, WebP): Opens the image in a centered modal.
       • For common text/code types (TXT, MD, CSV, JSON, HTML, JS, CSS, etc.): Fetches the file content and displays the first 10 lines in a modal with a textarea. An error message is shown if the content cannot be fetched.
     • Properties: Displays a modal with basic information about the selected item (Name, Type, Path, Size, Last Modified) in a textarea, allowing the user to copy the text.

7. Tooltips for Long Names:

   • If a file or folder name is too long to fit in the display, hovering over it will show a native browser tooltip with the full name.

8. Visual Feedback:

   • Loading spinner displayed during initial data fetch.
   • "Folder is empty" or "No search results" messages are displayed with an icon when appropriate.
   • Active sort criteria and direction are visually indicated.

9. Smooth Transitions:

   • CSS transitions are used for smoother expand/collapse animations of folders.

⁠Technical Aspects

1. Client-Side Rendering: The application is built entirely with HTML, CSS, and vanilla JavaScript, running in the browser.
2. No Proprietary Backend: It relies on a standard HTTP server to serve the static files (HTML, CSS, JS, icons/, libs/) and the data/ directory (including data.json and the actual files).
3. JSON Data Source: The file and folder structure is defined in a data.json file.
4. Local Asset Dependencies:
   • Bootstrap and Font Awesome (for some UI elements and chevron icons) are linked locally from a libs/ directory.
   • File/folder type icons are local SVG files stored in an icons/ (or libs/fontawesome/svgs/) directory.

This application provides a rich, client-side experience for browsing a pre-defined directory structure.

⁠Quick Start (HTTP)

1. Launch the container:

   docker run -d --name test-webfileexplorer -p 7173:80 -v $(pwd)/data:/config/www/data humbertovarona/webfileexplorer
   

   Copy
   • This maps the local ./data directory to /config/www/data inside the container, and exposes the service on port 7173.

2. Open in your browser:

   • Go to: http://ccc.nnn.sss.xxx:7173/

⁠Quick Start (HTTPS - With Automatic SSL Certificates)

⁠First Run (generates and stores SSL certs):

docker run -d --name test-webfileexplorer \
  -e REDIRECT_TO_HTTPS=yes -e AUTOCERT=yes \
  -p 7443:443 \
  -v $(pwd)/data:/config/www/data \
  -v $(pwd)/ssl:/config/ssl \
  humbertovarona/webfileexplorer

• This will generate SSL certificates in ./ssl (locally), and start the explorer on HTTPS port 7443.

⁠Subsequent Runs (reuse SSL certs):

docker run -d --name test-webfileexplorer \
  -e REDIRECT_TO_HTTPS=yes \
  -p 7443:443 \
  -v $(pwd)/data:/config/www/data \
  -v $(pwd)/ssl:/config/ssl \
  humbertovarona/webfileexplorer

• The same certificate directory (./ssl) is reused.

⁠Open in your browser:

• Go to: https://ccc.nnn.sss.xxx:7443/

⁠Managing the Container

⁠Stop the container:

docker stop test-webfileexplorer

⁠Remove the container:

docker rm test-webfileexplorer

⁠Remove the image:

docker rmi -f humbertovarona/webfileexplorer

⁠Troubleshooting & Diagnostics

⁠Check health status (if healthcheck is defined):

docker inspect --format='{{json .State.Health}}' test-webfileexplorer | jq

⁠View container logs:

docker logs test-webfileexplorer

⁠Enter the container shell:

docker exec -it test-webfileexplorer /bin/sh

⁠Using docker-compose

You can also deploy Web File Explorer with docker-compose:

version: "3"
services:
  webfileexplorer:
    image: humbertovarona/webfileexplorer
    container_name: test-webfileexplorer
    ports:
      - "7173:80"
      # - "7443:443"   # Uncomment for HTTPS
    volumes:
      - ./data:/config/www/data
      # - ./ssl:/config/ssl   # Uncomment for HTTPS
    environment:
      # - REDIRECT_TO_HTTPS="yes"    # Uncomment for HTTPS
      # - AUTOCERT="yes"             # Only for the first HTTPS run
      - TIMEZONE=America/Recife
    restart: unless-stopped

⁠## Related Tools

• makeindex.sh⁠ is a Bash script for recursively scanning a directory and generating a structured JSON index describing all files and folders, including metadata such as size, type, extension, and last modified date. This is ideal for building web-based file explorers or any system needing a directory listing in machine-readable format.

• setwebperms.sh⁠ is a Bash script for recursively setting recommended permissions for web directories: it ensures all directories have 755 permissions and all files have 644 permissions, which is best practice for serving static content securely with web servers such as Nginx or Apache.

⁠Notes

• Replace ccc.nnn.sss.xxx with your Docker host's IP address.
• Ensure ports 7173 (HTTP) and/or 7443 (HTTPS) are not in use by other applications.
• For custom domain or Let's Encrypt support, additional configuration may be required.

⁠Credits

• Development & Maintenance: Humberto Varona
• Contact: [email protected]⁠

⁠License

This document and the project are released under the CC0 1.0 Universal (public domain) license.