flag Getting Started

Step-by-step guide to set up your BoomStick development environment.

info Choose your module name. "bang" is used throughout these instructions. Replace "bang" with whatever you choose as your module name in ALL commands.
1
Clone the Repository

Start by cloning the BoomStick repository to your local machine.

git clone https://github.com/cedarcoasters/boomstick.git BoomStick-bang
2
Navigate to Project Directory

Change into the main repository directory.

cd BoomStick-bang
3
Explore the Module Generator

BoomStick includes a module generator script. Check out its help documentation to understand available options.

./bin/make-module --help
4
Create Your Entry Point Module

Create an entry point module. This serves as the main entry point for your application and is referenced by the NginX configuration.

./bin/make-module -m bang
info Tip: Replace bang with your desired module name. Entry modules are prefixed with entry- automatically.
5
Initialize the Entry Module

Run the initialization script to create the NginX configuration for your entry module.

cd module/entry-bang && ./entry-init.sh && cd ../../
6
Install Development Tools (Node.js Module)

Install the base development tools using the nodejs module. This creates a standalone module that manages npm dependencies and copies the necessary vendor files into your entry module.

./bin/make-module -t nodejs --entry-point-module=bang -m bang
info Note: The nodejs module inherits all npm dependencies and handles vendor file management, keeping your entry module clean.
7
Build Vendor Assets

Navigate to the nodejs module directory and run npm to install dependencies and build vendor assets.

cd ./module/nodejs-bang/ && npm install && npm run all
check_circle This installs the necessary vendor files into module/entry-bang/public/js/vendor/.
8
Install PHP Composer Module

Install the PHP Composer module to manage PHP dependencies for your entry module.

cd ../../ && ./bin/make-module -t composer --entry-point-module=bang -m bang
9
Initialize Composer Autoloader

Run the initialization script to install the autoloader reference into your entry module's index file.

cd ./module/composer-bang && ./init-entry.sh
check_circle This adds the vendor autoloader include to your entry module's public/index.php.
10
Build and Run with Docker

Finally, use Docker Compose to build the project and start your development environment.

cd ../../ && docker compose up --build
11
View Your Application

Open your web browser and navigate to your local development server.

http://localhost:8000/
check_circle Groovy! You should now see the default BoomStick landing page. Your development environment is fully configured!

folder_open Project Structure

Understanding the BoomStick directory structure will help you navigate and extend your application.

BoomStick/
├── bin/                        # Executable scripts (make-module, etc.)
├── docker-config/              # Docker configuration files
│   └── nginx/                  # NginX server configuration
├── init/                       # Initialization scripts
├── lib/                        # Core framework libraries
├── module/                     # Application modules
│   ├── composer-bang/          # PHP Composer dependency module
│   │   ├── composer.json       # Composer configuration
│   │   ├── init-entry.sh       # Autoloader initialization script
│   │   └── vendor/             # Composer dependencies
│   ├── entry-bang/             # Main entry point module
│   │   ├── controller/         # MVC Controllers
│   │   ├── lib/                # Module-specific libraries
│   │   ├── public/             # Publicly accessible files
│   │   │   ├── css/            # Stylesheets
│   │   │   │   └── vendor/     # Vendor CSS (from nodejs module)
│   │   │   ├── js/             # JavaScript files
│   │   │   │   └── vendor/     # Vendor JS (from nodejs module)
│   │   │   └── index.php       # Application entry point
│   │   ├── render/             # Rendering components
│   │   │   ├── element/        # Reusable elements
│   │   │   ├── layout/         # Page layouts
│   │   │   ├── script/         # Inline scripts
│   │   │   ├── style/          # Inline styles
│   │   │   └── view/           # View templates
│   │   └── route/              # URL routing definitions
│   └── nodejs-bang/            # Node.js build tools module
│       ├── node_modules/       # npm dependencies
│       └── package.json        # npm configuration
├── template/                   # Module templates for generator
├── test/                       # Test files
├── docker-compose.yml          # Docker Compose configuration
└── README.md                   # Project documentation

widgets Module Anatomy

Each BoomStick module follows the MVC pattern with additional organizational components.

settings_remote
Controllers

Handle HTTP requests, process business logic, and coordinate between models and views.

controller/*.ctlr.php
visibility
Views

Render HTML templates with data passed from controllers.

render/view/*.view.php
view_quilt
Layouts

Define the overall page structure that wraps your views.

render/layout/*.layout.php
extension
Elements

Reusable partial templates (headers, footers, widgets).

render/element/*.element.php
alt_route
Routes

Map URLs to controller actions.

route/*.route.php
library_books
Libraries

Module-specific classes and utilities.

lib/*.class.php

arrow_forward Next Steps

add_circle Create More Modules

Use the module generator to create additional modules for your application.

./bin/make-module -m mymodule
edit Customize Your Module

Edit the generated files to build your application:

  • Add routes in route/
  • Create controllers in controller/
  • Design views in render/view/