Bundla – Laravel in Docker

A quick way to create a Laravel project for development!

Bundla is a console utility for raising the development environment on Laravel + Docker, with the necessary configuration and environment.

Table of contents

• How it works?
• Supported OS
• Dependencies
• Installing Bundla
• Install Laravel bundle
• Commands
• Project Supported Bundles
• Project Supported Modules
• Structure of the created projects
• How to create your Laravel bundle?
• How to create your Docker Compose module?
• Images Docker
• Versioning
• Contributing
• License

How it works?

Install the Bundla console utility. Find the desired bundle and install it with one command.

Bundla will automatically install the specific version of Laravel, generate the files docker-compose.yml, composer.json, package.json, .env for Laravel, .env for Docker Compose and launch the containers.

The created projects are based on the «Laravel bundles», which consist of Laravel parameters, instructions and «Docker Compose modules».

Laravel bundle – a set of parameters, instructions and Docker Compose modules for creating a complete development environment for Laravel and Docker.

Docker Compose module – a set of parameters for forming a Docker container.

In addition, the Bundle allows you to quickly execute the Docker Compose commands and Shell commands inside the «app» container.

Supported OS

• Ubuntu >= 16.04
• Debian >= 9
• MacOS >= 10.14.6

Dependencies

• Git
• Docker
• Docker Compose

Bundla installer will automatically install dependencies on Linux.

On MacOS, you need to install the dependencies manually before installing Bundla.

Installing Bundla

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/tgaru/bundla/master/install.sh)"

Install Laravel bundle

1. Create a new folder for your project and go to it.

   mkdir project && cd ./project

2. Install the desired Laravel bundle

   bundla i bundla/laravel-7.6-lite

   This example install Laravel bundle bundla/laravel-7.6-lite.

   You can specify the version of the bundle (repository release) through a colon, Example:

   bundla i bundla/laravel-7.6-lite:^1.0

Commands

Command	Description
bundla i <bundle-key>	Install Laravel bundle
bundla create bundle	Create a new bundle based on a template
bundla create module	Create a new module based on a template
bundla app "<shell-command>"	Run the command inside the container «app»
bundla help	Bundla Command List
bundla app	Analogue [docker-compose exec app sh]
bundla ps	Analogue [docker-compose ps]
bundla up	Analogue [docker-compose up -d]
bundla down	Analogue [docker-compose down]
bundla build	Analogue [docker-compose build]
bundla restart	Analogue [docker-compose restart]
bundla stop	Analogue [docker-compose stop]
bundla start	Analogue [docker-compose start]

Project Supported Bundles

Bundle key name	Title
bundla/laravel-7.6-lite	Laravel 7.6 Lite
bundla/laravel-7.6-postgres	Laravel 7.6 + PostgreSQL
bundla/laravel-7.6-mysql	Laravel 7.6 + MySQL
bundla/laravel-7.6-horizon	Laravel 7.6 + Horizon
bundla/laravel-7.6-vue-postgres	Laravel 7.6 + Vue + PostgreSQL
bundla/laravel-7.6-vue-mysql	Laravel 7.6 + Vue + MySQL
bundla/laravel-7.6-tgbot-vue-postgres	Laravel 7.6 + Telegram Bot SDK + Vue + PostgreSQL
bundla/laravel-7.6-tgbot-vue-mysql	Laravel 7.6 + Telegram Bot SDK + Vue + MySQL

Project Supported Modules

Module key name	Docker Image
bundla/m-app-php-7.2	tgaru/bundla-php:7.2
bundla/m-nginx-latest	tgaru/bundla-nginx:latest
bundla/m-scheduler-php-7.2	tgaru/bundla-php:7.2
bundla/m-horizon-php-7.2	tgaru/bundla-php:7.2
bundla/m-postgres-12.3	postgres:12.3
bundla/m-mysql-8.0	mysql:8.0
bundla/m-redis-6.0	redis:6.0

Structure of the created projects

project
├── .env
├── .env.example
├── .gitignore
├── docker-compose.yml
└── src/
    ├── .env
    ├── .env.example
    ├── composer.json
    ├── package.json
    └── ...Laravel files and folders...

.env – environment variables for Docker Compose

.env.example – copy of the .env file

.gitignore – Git ignored data file (optional)

docker-compose.yml – Docker Compose main configuration file

src/ – folder loaded with Laravel

src/.env – environment variables for Laravel

src/.env.example – copy of the src/.env file

src/composer.json – config file Composer

src/package.json – config file NPM

The content of these files varies depending on the bundle.

How to create your Laravel bundle?

1. Run the command bundla create bundle.

2. Enter the data according to the instructions in the console. As a result, the directory ~/.bundla/vendor/bundles/<your-github-username>/<your-repo-name> will be created.

3. In this directory, open the bundle.yml file. You will see the following template:

   bundle.yml

   version: "1"
   title: <bundle-title>
   description: <bundle-description>
   repository-url: https://github.com/laravel/laravel.git
   repository-version: <repository-version>
   docker-compose:
     modules:
       <docker-compose-module>: <docker-compose-module-version>
       <...other-docker-compose-modules...>
   composer:
     install: true
     expansion: true
     require-dev:
       <composer-package-name>: <composer-package-version>
       <...other-composer-packages...>
     require:
       <composer-package-name>: <composer-package-version>
       <...other-composer-packages...>
   npm:
     install: false
     expansion: true
     devDependencies:
       <npm-package-name>: <npm-package-version>
       <...other-npm-packages...>
     dependencies:
       <npm-package-name>: <npm-package-version>
       <...other-npm-packages...>
   app-cmd-before:
     - <cmp-before-command>
     <...other-cmp-commands...>
   app-cmd-after:
     - <cmp-after-command>
     <...other-cmp-commands...>

4. Customize the config according to your needs:

   Parameter List

   <bundle-title> - the name of the bundle (for convenience).

   <bundle-description> - description of the bundle (for convenience).

   <repository-version> - version of Laravel (repository releases) or range of versions.

   <docker-compose-module> - Docker Compose modules, which, when installed, are combined into docker-compose.yml, forming .env files.

   There MUST be a module containing the «app» service.

   Example: bundla/m-redis-6.0: ^1.0 (will include versions up to 2.0)

   <composer-package-name> - the name Composer package.

   If composer.expansion = true is set, the packages will complement the existing packages in the composer.json file.

   Otherwise, only the packages specified in bundle.yml will be used.

   <composer-package-version> - Composer version of the package.

   <npm-package-name> - the name of the NPM package.

   If the npm.expansion = true parameter is set, the packages will complement the existing packages in the package.json file.

   Otherwise, only packages specified in bundle.yml will be used.

   <npm-package-version> - version of NPM package.

   <cmp-before-command> - commands that are executed before installing Composer and NPM packages. Executed in the container «app».

   <cmp-after-command> - commands that are executed after installing Composer and NPM packages. Executed in the container «app».

   If composer.install is set to false, the composer install command will not be run.

   If npm.install is set to false, the npm install command will not be run.

5. Installing your bundle.

   Create a new folder and go to it:

   mkdir new_project

   Install the bundle:

   bundla i <your-github-username>/<bundle-key-name>

6. Now you can upload the bundle to your Github repository so you can install it quickly anytime.

Additionally

You can put your composer.json and package.json files in the bundle folder. In this case, the files will be replaced first, and then the packages will be added from the bundle.yml file.

Examples of bundles can be found in the «Project Supported Bundles» section.

How to create your Docker Compose module?

1. Run the command bundla create module.

2. Enter the data according to the instructions in the console. As a result, the directory ~/.bundla/vendor/modules/<your-github-username>/<your-repo-name> will be created.

3. In this directory, open the module.yml file. You will see the following template:

   module.yml

   version: "1"
   print:
     - "Text output after installation"
     - "Text from a new line"
   env:
     docker-compose:
       <env-parameter-name>: <env-parameter-value>
       <...other-env-parameters...>
     laravel:
       <env-parameter-name>: <env-parameter-value>
       <...other-env-parameters...>
   service:
     <service-name>:
       image: <image-name>
       <service-parameter-name>: <service-parameter-value>
       <...other-service-parameters...>
   volume:
     <volume-name>:
       <volume-parameter-name>: <volume-parameter-value>
       <...other-volume-parameters...>

4. Customize the config according to your needs:

   Parameter List

   In the env.docker-compose section, list all the parameters used in the service section that you want to transfer to the .env file (if required).

   In the env.laravel section, list all the parameters for Laravel to work correctly with your Docker Compose service. These parameters will be saved in the src/.env file (if required).

   In the service section, place the service that will be transferred to the docker-compose.yml file in the services section.

   In the volume section, place the volume that will be transferred to the docker-compose.yml file in the volumes section (if required).

5. Your Docker Compose module is ready. Now it can be used in the Laravel bundle, in the docker-compose.modules section.

6. Now you can load the module into your Github repository to conveniently include it to a bundle.

Additionally

Examples of modules can be found in the «Project Supported Modules» section.

Images Docker

A list of images compiled specifically for the project, as well as their source code, can be found here.

Other images can be found at hub.docker.com.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Contributing

Contributions are welcome! Leave an issue on Github, or create a Pull Request.

License

Bundla is distributed under the MIT license. See LICENSE for details.