Homepage

Homepage by tomershvueli is a lightweight, self‑hosted personal dashboard written in PHP. Its core purpose is to provide a single entry point into a user’s server or web services, presenting a clean UI that updates its background image from Unsplash (or a custom source) every few seconds while offering an optional icon‑based menu. The application is intentionally minimalistic, with all static assets bundled in the repository so it can run offline. From a developer’s standpoint, the codebase is straightforward: an Apache‑served PHP page that pulls configuration from a JSON file, uses cURL to fetch images, and relies on jQuery for DOM manipulation. The front‑end is built with Bootstrap CSS, Font Awesome icons, and Mousetrap.js for keyboard shortcuts.

Technical Stack & Architecture

• Backend: PHP 7+ with cURL extension for HTTP requests. The application parses a config.json file to drive runtime behavior, exposing a small set of configuration knobs such as unlock patterns, clock format, and idle timers.
• Web Server: Apache (or any PHP‑capable web server) is required; the code contains no framework dependencies, making it trivially portable.
• Frontend: Bootstrap 4 for responsive layout, jQuery 3.x for event handling, Mousetrap.js to map keyboard shortcuts to actions (e.g., toggling the menu), and Font Awesome for iconography.
• Background Images: Optional integration with Unsplash’s API (requires a client ID). If the demo key is used, rate limits are respected by default (time_to_refresh_bg set to 20 s). Custom image URLs can be supplied via a JSON selector, bypassing external calls.

The architecture is essentially a single‑page application (SPA) served by PHP, with the only dynamic data coming from the JSON config and optional API calls. There is no database layer; all state is static or derived from the request context.

Core Capabilities & Extensibility

• Dynamic Backgrounds: Pulls a new image from Unsplash or a custom source every time_to_refresh_bg milliseconds, using PHP cURL for the HTTP request.
• Menu Grid: Configurable list of links (items) rendered as a 3‑column grid. Each item can use an icon or custom image, open in the same tab or a new one, and include tooltips.
• Keyboard Interaction: Mousetrap.js enables a customizable unlock pattern (unlock_pattern) that can trigger menu visibility or other actions.
• Idle Timer: Optional auto‑hide of the menu after a specified period of inactivity (idle_timer).
• Clock Overlay: Displays current time using PHP’s date() function, with a configurable format (clock_format).
• Extensibility: While the project itself is minimal, developers can easily extend functionality by adding new PHP functions to fetch data (e.g., weather, system stats) and exposing them through the menu or as widgets. The front‑end can be swapped for a more feature‑rich framework if desired, thanks to its modular asset structure.

Deployment & Infrastructure

Because the application is purely PHP and static assets, it can be deployed on any LAMP stack or containerized using Docker. The repository contains a Dockerfile that builds an image with Apache and PHP pre‑installed, simplifying CI/CD pipelines. Scalability is limited only by the web server; multiple instances can be load‑balanced behind a reverse proxy if a single user is not the primary use case. The absence of a database or stateful service means zero‑downtime deployments and easy rollbacks.

Developer Experience

• Configuration: A single config.sample.json file outlines all tunable options, making onboarding fast.
• Documentation: The README provides clear explanations of each config field and links to external resources (Unsplash, Mousetrap).
• Community: The project is listed in the Awesome Self‑hosted catalog and has a modest issue tracker, offering quick support for edge cases such as Unsplash API key revocation.
• License: The repository is open source (MIT), encouraging modification and redistribution without licensing concerns.

Use Cases

1. Personal Server Dashboard – A developer hosting multiple services (e.g., Plex, Nextcloud) can use Homepage as a single landing page that updates its background and offers quick links.
2. IoT / Home Automation – By extending the PHP layer to query device status, a homeowner can embed smart‑home controls into the same UI.
3. Internal Team Portal – Teams can deploy a lightweight intranet front‑page that links to internal tools, with custom branding via background images.
4. Developer Showcase – A dev can host a personal website that demonstrates their tech stack, using the menu to link to repositories or projects.

Advantages Over Alternatives

• Zero Dependencies – No frameworks, no database, minimal server footprint.
• Fast Deployment – A single PHP file plus assets; Docker image available for instant scaling.
• Customizable UI – All visual elements are driven by JSON, allowing rapid iteration without code changes.
• License Friendly – MIT license and royalty‑free Unsplash images mean no cost or legal hurdles.
• Keyboard Friendly – Mousetrap integration gives a tactile, keyboard‑centric experience uncommon in other dashboards.

Overall, Homepage offers a lean