Deployment: Docker

The PriceBuddy application is designed to be deployed using Docker, which is the easiest and recommended installation method. This approach encapsulates the application and its dependencies into a set of containerized services, ensuring a consistent and reproducible environment. The deployment is orchestrated using Docker Compose, which manages the application container, a database, and other required services.

The core of the deployment is a multi-stage Docker build process that compiles frontend assets and installs dependencies in a builder container before creating a lean final application image. This final image includes the Laravel application, a web server (Apache), and a cron daemon for running background tasks, all managed by Supervisor.

Service Architecture

The application's services are defined in docker-compose.yml. While the file itself is not provided in the context, its structure can be inferred from the README.md and container startup scripts. The primary services include the application itself, a database, and Redis for caching/queuing.

The following diagram illustrates the high-level service architecture as orchestrated by Docker Compose.

Services Overview

Based on the project's documentation and startup scripts, the following services are part of the Docker setup.

Sources: README.md:38-41, docker/php/start-app.sh:23-27

Docker Image Build Process

The application image is built using a multi-stage Dockerfile to optimize the final image size by excluding build-time dependencies.

Sources: docker/php.dockerfile

This diagram shows the multi-stage build process, starting from a base PHP image, building dependencies and assets in a builder stage, and finally assembling the lean production image.
Sources: docker/base.dockerfile, docker/php.dockerfile

Base Image (base.dockerfile)

The foundation of the application image is jez500/pricebuddy-base, which is built from docker/base.dockerfile. This image starts with a standard php-apache image and adds necessary system packages and PHP extensions.

• OS Packages: Installs cron, supervisor, zip, unzip, netcat-traditional, and MySQL client tools.
• PHP Extensions: Installs exif, pcntl, posix, mysqli, pdo_mysql, pdo_pgsql, zip, and intl.
• Composer: Installs Composer globally.

Sources: docker/base.dockerfile:5-22

Application Image (php.dockerfile)

This file defines a two-stage build to create the final pricebuddy image.

Builder Stage

This stage prepares all necessary dependencies and built assets.

1. Source Code: Copies the entire application source code into the container.
2. PHP Dependencies: Runs composer install --no-dev to install backend dependencies.
3. Frontend Assets: Runs npm install && npm run build to compile JavaScript and CSS assets.
4. Documentation: Builds the VuePress documentation site.

Sources: docker/php.dockerfile:4-14

Final Stage

This stage assembles the production-ready image.

1. Base: Starts from the jez500/pricebuddy-base image.
2. Copy Artifacts: Copies the application source code, along with the vendor directory, public/build assets, and public/docs from the builder stage.
3. Configuration: Copies custom php.ini, schedule-cron for cron jobs, and supervisord.conf for process management.
4. Scripts: Copies the start-app.sh and start-cron.sh scripts into the container.
5. Setup:
   • Creates a symbolic link from /app/public to Apache's web root /var/www/html.
   • Enables Apache's mod_rewrite.
   • Sets executable permissions on startup scripts.
   • Creates required storage directories.
6. Final Command: Sets the container's default command to execute /start-app.sh.

Sources: docker/php.dockerfile:16-43

Container Initialization

When the app container starts, it executes the /start-app.sh script to initialize the application environment.

This diagram shows the sequence of commands executed by the start-app.sh script.

The key initialization steps are:

1. Environment File: If an .env file does not exist, it is created from .env.example and an application key is generated.
2. Storage: Ensures all necessary storage subdirectories exist and sets their permissions to 777. A symbolic link for public storage is also created.
3. Database Check: The script enters a loop, using netcat to wait until the database service is available on the host and port defined by DB_HOST and DB_PORT.
4. Database Initialization: Runs php artisan buddy:init-db, which handles migrations and seeding.
5. Application Caching: A series of artisan commands are run to optimize the application by caching configuration, routes, events, and icons. It also regenerates the price cache.
6. Process Management: Finally, supervisord is started to manage the Apache web server and the cron daemon, making the application accessible and ensuring background tasks are run.

Sources: docker/php/start-app.sh:4-40

Background Tasks

Background tasks, such as fetching prices and sending notifications, are handled by a cron job running inside the app container.

• The docker/php/schedule-cron file is copied to /etc/cron.d/ in the container.
• supervisord is configured via supervisord.conf to start the cron service.
• The README.md confirms that the cron job handles background tasks automatically.

Sources: README.md:53-55, docker/php.dockerfile:26, docker/php.dockerfile:27, docker/php/start-app.sh:40