Skip to content

Conversation

@zaidmasri
Copy link

Description
This PR introduces a Docker-based local development environment for Gibbon Core. It modernizes the repository's tooling by providing a standardized containerized setup, eliminating "works on my machine" issues.

The setup is split into two modular configuration files:

  • docker-compose.yaml: The base configuration defining the core services (app and db), networks, and volumes suitable for production-like builds.
  • docker-compose.dev.yaml: A development override that exposes ports (e.g., 8080) and sets environment variables specifically for local testing.

Motivation and Context
Currently, setting up a local Gibbon development environment requires manually configuring PHP, Apache, and MySQL, which can be error-prone and inconsistent across operating systems (macOS, Windows, Linux).

This change solves the following problems:

  • Simplifies Onboarding: New contributors can spin up a fully working instance with a single command.
  • Dependency Management: Ensures all contributors use the exact same PHP version (8.2) and extensions (bcmath, intl, gd, etc.) required by Gibbon v31+.
  • Isolation: Keeps the database and application files isolated from the host machine, preventing system clutter.

How Has This Been Tested?
I have tested these changes on macOS (Intel) using Docker Compose CLI and deployed to a production-like environment using Coolify.

Test Scenarios:

  1. Fresh Install: verified that running the dev command spins up containers, and the Gibbon Web Installer is accessible at http://localhost:8080.
  2. Database Connection: Verified that the app container can successfully communicate with the db container using the hostname db and default credentials.
  3. Extension Compatibility: Confirmed that critical PHP extensions (bcmath, gd, zip) are loaded and functional.
  4. Deployment (Coolify): Validated the configuration by deploying via Coolify, ensuring the image builds correctly and runs in a self-hosted production context.

How to Run (Instructions for Reviewers)

Option 1: Local Development (Recommended)
This command uses the override file to expose the app on port 8080.

docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build

Option 2: Production/Base Build
To test the standalone base configuration (no ports exposed to host by default, mimics production internal networking):

docker compose up -d --build

Shutdown:
To stop containers and remove volumes (resetting the database):

docker compose down -v

Screenshots

Local
image

image

VPS

Below is the configuration used to deploy this branch via Coolify. By pointing the setup wizard to the fork containing these Docker files, the platform automatically handled the build and deployment process without manual intervention.

Screenshot 2025-12-12 at 2 04 43 AM

Future Enhancements

  • Dynamic Extension Loading: Support for installing additional PHP extensions via build arguments or configuration files.

  • CI/CD Pipeline Integration: Automate the build and publication of the Docker image to a container registry (e.g., GHCR). This will allow users to pull a pre-built image rather than building from source locally.

  • Headless Provisioning: Enable full instance configuration via environment variables to bypass the web-based installation wizard, facilitating automated/unattended deployments.

I would appreciate your feedback on edge cases you perceive, particularly if I were to use this as a production build

@zaidmasri
Copy link
Author

@SKuipers is there anything I can do to help make this easier for your review?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant