Getting Started (Installation)

PriceBuddy is an open-source, self-hostable web application for comparing product prices from various online retailers. This guide provides a comprehensive overview of the installation process, focusing on the recommended Docker-based setup. The primary method leverages Docker Compose for a simple and reproducible deployment.

Alternative installation methods are not recommended due to the complexity of the application and its dependencies. However, for advanced users, this guide also outlines the necessary components based on the project's Docker configuration files. For development-specific setup, refer to the Development section.

Sources: README.md:1-5, 41-46

Docker Installation

The easiest and recommended installation method for PriceBuddy is using Docker Compose. This approach encapsulates the application and its services (web server, database, etc.) into manageable containers.

Sources: README.md:38-40

Prerequisites

• Docker and Docker Compose must be installed on your system.

Docker Architecture

The docker-compose.yml file (as described in the README.md) orchestrates the various services required for the application to run. The core service is the app container, which runs the Laravel application on a PHP-Apache image.

The diagram below illustrates the high-level architecture of the services.

Step-by-Step Installation

1. Create docker-compose.yml: Make a copy of the docker-compose.yml file from the repository. You can tweak this file to your liking (e.g., change ports or volumes).
2. Create .env file: Create an empty environment file. The application will use this for configuration.

   touch .env
   

3. Start the containers: Run Docker Compose in detached mode.

   docker compose up -d
   

4. Access the application: If using the default settings, the application will be available at http://localhost:8080.
5. Default Credentials:
   • Username: admin@example.com
   • Password: admin

Sources: README.md:38-40

Container Startup Process

When the app container starts, it executes the /start-app.sh script, which performs several initialization tasks.

The following flowchart outlines the startup sequence:

Docker Image Build Process

The application's Docker image is built using a multi-stage process defined in docker/php.dockerfile and docker/base.dockerfile.

1. Base Image: The build starts from a php:${PHP_VERSION}-apache-bookworm image. It installs system dependencies like cron, supervisor, zip, and various PHP extensions.
   • PHP Extensions: exif, pcntl, posix, mysqli, pdo, pdo_mysql, pdo_pgsql, zip, intl.
   • Composer: The Composer binary is copied into the image.
2. Builder Stage: This stage uses a jez500/pricebuddy-tests-${PHP_VERSION}:latest image. It copies the application code, installs Composer dependencies (composer install --no-dev), and builds the frontend assets (npm install && npm run build).
3. Final Stage: The final image is based on jez500/pricebuddy-base-${PHP_VERSION}:latest. It copies the application code, the vendor directory from the builder stage, and the built frontend assets. It then sets up cron, supervisord, and the Apache web server.

Background Tasks (Cron)

The Docker container includes a cron job to handle background tasks like fetching prices and sending notifications. This is managed by supervisord alongside the Apache web server.

The cron job is configured via the /etc/cron.d/schedule-cron file, which is copied into the image during the build process.

Sources: README.md:52-54, docker/php.dockerfile:20, 23

Alternative Installation Methods

Due to the application's complexity, installation methods other than Docker are not recommended. If you wish to proceed without Docker, you must manually set up the required environment. The docker/php.dockerfile, docker/base.dockerfile, and composer.json files provide a reference for the necessary dependencies.

Sources: README.md:41-46

System Requirements

• composer
• A web server (e.g., Apache with mod_rewrite enabled)
• A database (e.g., MySQL, PostgreSQL)
• npm for frontend asset compilation
• cron for background tasks

Sources: composer.json:7, docker/base.dockerfile:9-18, docker/php.dockerfile:12, 21

Development Environment

For development, the project uses Lando. This simplifies the setup of a local development environment.

To get started with development:

1. Install Lando.
2. Clone the repository.
3. Navigate into the project directory (cd pricebuddy).
4. Run lando start.

This will provision all the necessary services for development. The composer.json file also includes a dev script which uses concurrently to run the PHP server, queue worker, log tailing, and Vite dev server simultaneously.

Sources: README.md:60-64, 88-92