localhost

This project provides easy to use docker based development environment for your projects. All the modules are selective & can be enabled based on Environment file (.env)! Supports multiple domains.

1. This is for local development only!
2. Don't state both apache & nginx in COMPOSE_PROFILES.
3. Domain(s) should be available in the hosts file <your_ip> <your_domain>.

Prerequisites (Docker)

Install docker on your system first. If you already have docker installed, you can skip this step.

• To install on Linux, it is recommended to use Docker Engine.
• To install on other OS, use Docker Desktop (although you can also install this on linux as well).

The directory structure

For using your projects with this, by default you should arrange your projects structure as follows,

| application
       |- site1
       |- site2
       |- site3
       |- .....
| localhost (this repository)

But the project structure is flexible. If wanna change the directory of your projects (set other custom path instead of same level application directory), just change/add the PROJECT_DIR in .env file, which should point to your project directory.

PROJECT_DIR=../path/to/your/projects/directory # supports relative/absolute path

Now lets look into the localhost structure for where your configuration files should be.

| localhost
       |- bin
       |- configuration # this is where you should put your configuration files
             |- apache # your apache Site configuration files (example available in directory)
             |- nginx # your nginx Site configuration files (example available in directory)
             |- php # your php configuration file (php.ini)
             |- ssh # your ssh keys (needed specifically for git ssh authentication)
             |- ssl # your ssl certificates
       |- docker # this directory should stay untouched
             |- compose # docker compose file(s)
             |- conf # docker configuration files
             |- data # docker data files for persistence
             |- logs # container logs
       |- .env
       |- cruise
       |- cruise.bat

Run the server, the easiest way

• Simply, create .env file, place your settings.
• Create site configuration file in localhost/configuration/(nginx or apache). Example configuration available in those directories.
• Don't forget to add host file entry for your domain(s) in your local machine.
• Run cruise start or ./cruise start (on linux you must run chmod +x cruise first)
• Your site(s) will be available in your desired domain(s)

Usage

Note: on linux you must run chmod +x cruise first

• ./cruise start/relaod or cruise start/reload to start the server or reload with updated Environment variables
• If you want to enter in PHP container shell, simply run cruise core or ./cruise core
• To stop the server, simply run cruise stop or ./cruise stop
• To restart/reboot the server, simply run cruise restart/reboot or ./cruise restart/reboot
• To rebuild the server, simply run cruise rebuild <service_name> or ./cruise rebuild <service_name>
• Launch Docker CLI GUI using cruise lzd or ./cruise lzd
• You can run any docker compose command using cruise <command> or ./cruise <command> (except the above-mentioned ones)

Modules & Other main settings

Modules (Docker Images, Linux Packages, PHP Versions & Extensions, NodeJS) are controlled based on the environment variables. Checkout the .env.example file for example. To further understand these keep reading further.

1. Sync the system user

Sync the internal docker user with the system user using the environment variable UID. In case of linux you can get this using id -u command which is the UID of current user. In case of windows, you can get with same command if you use cmder terminal or git-bash.

UID=1000

2. Selecting the docker image

To select the docker image, we used the environment variable COMPOSE_PROFILES. You will include your required modules in CSV format (i.e. nginx,mysql). Here are the list of modules you can state here,

• nginx loads nginx image with php (service: web, php)
• apache loads apache with php (service: app)
• mysql or mariadb loads mysql/mariadb with phpmyadmin (service: mysql-server, mysql-client)
• postgresql loads postgresql & pgadmin (service: postgres-server, postgres-client)
• mongodb loads mongodb & mongo express (service: mongo-server, mongo-client)
• elasticsearch loads elasticsearch & kibana (service: elasticsearch-server, elasticsearch-client)
• redis loads redis & redis insight (service: redis-server, redis-client)
• tools loads server tools (check below for more info) (service: server-tools)

Note: don't include both nginx & apache

COMPOSE_PROFILES=nginx,postgresql

3. PHP version

Select the PHP version using the environment variable PHP_VERSION. Supports single PHP version.

PHP_VERSION=8.3

4. PHP extensions

List your required PHP extensions using the environment variable PHP_EXTENSIONS. Supports CSV formatted list. For the list of available modules please refer to mlocati docker extension list. Latest composer will be installed by default, no need to specify it.

PHP_EXTENSIONS=bcmath,zip,gd

5. Linux packages

To install additional linux packages we used the environment variable LINUX_PACKAGES. These extensions are additional & not related to your php extensions (as those will be auto installed by PHP_EXTENSIONS). Supports CSV formatted values.

LINUX_PACKAGES=git,curl

6. Node.js

Your project is also using node.js? To install it, we used the environment variable NODE_VERSION. Support major version number (i.e. 18/20/...). Also, supports either of lts or current as well. Check node.js debian source for more details. Leaving this empty, won't install node.js.

NODE_VERSION=lts

7. Environment variables

In addition to the above, you can define the following environment variables as you see fit.

• TZ Timezone (default: Asia/Dhaka)

nginx/apache

• HTTP_PORT http port (default: 80)
• HTTPS_PORT https port (default: 443)

php

• PHP_VERSION PHP version (default: 8.3)
• UID The uid of system user (default: 1000)
• PHP_EXTENSIONS List of php extensions in csv format
• LINUX_PACKAGES List of linux packages in csv format
• NODE_VERSION If node.js is required, specify version

mariadb/mysql

• MYSQL_IMAGE What you wanna use? mariadb or mysql (default: mariadb)
• MYSQL_VERSION The version for mariadb or mysql (default: latest)
• MYSQL_PORT DB port (default: 3306)
• MYSQL_ROOT_PASSWORD Root user password (default: 12345)
• MYSQL_USER DB User (default: devuser)
• MYSQL_PASSWORD DB password (default: 12345)
• MYSQL_DATABASE DB name (default: localdb)

mariadb/mysql client (PHPMyAdmin)

• MYADMIN_PORT The client access port (default: 3300)

postgres

• POSTGRESQL_VERSION The version for PostgreSQL (default: latest)
• POSTGRESQL_PORT DB port (default: 5432)
• POSTGRES_USER DB user (default: postgres)
• POSTGRES_PASSWORD DB password (default: postgres)
• POSTGRES_DATABASE DB name (default: postgres)

postgres client (PgAdmin 4)

• PGADMIN_PORT The client access port (default: 5400)

mongodb

• MONGODB_VERSION The version for MongoDB (default: latest)
• MONGODB_PORT DB port (default: 27017)
• MONGODB_ROOT_USERNAME username (default: root)
• MONGODB_ROOT_PASSWORD password (default: 12345)

mongodb client (Mongo Express)

• ME_VERSION App version (default: latest)
• ME_BA_USERNAME Basic Auth User (default: root)
• ME_BA_PASSWORD Basic Auth Password (default: 12345)

elasticsearch

• ELASTICSEARCH_VERSION ElasticSearch version (default:8.12.2)
• ELASTICSEARCH_PORT ES port (default: 9200)

elasticsearch client (Kibana)

• KIBANA_PORT The client access port (default: 5601)

redis

• REDIS_VERSION Redis version (default: latest)
• REDIS_PORT Redis port (default: 6379)

redis client (Redis Insight)

• RI_PORT The client access port (default: 5540)

CLI Utilities

You can add the localhost/bin directory, to your PATH environment variable for global usage of several commands. These will be available depending on what you enable in COMPOSE_PROFILES.

** If you have any other docker container running with the same name as of this docker container names, it will end up in conflict!

Available commands:

• php
• mysql
• mysqldump
• mariadb
• mariadb-dump
• psql
• pg_dump
• pg_restore
• redis-cli
• lzd # Docker CLI GUI
• cert # Generate ssl certificates, in case you don't have it
  • Certificate(s) will be generated directly inside the configuration/ssl directory
  • usage: cert site1.internal site2.com *.site3.com .....

In windows, it is recommended to use cmder terminal or git-bash for better experience.

Server Tools

Well, you can use these tools to help you out. We have created a list of them below. These tools can help you do several things. This container mounts your application directory as /app inside the container. So you can use these tools on all your projects.

Usable outside docker container:

• lzd # Docker CLI GUI
• cert # Generate ssl certificates, in case you don't have it
  • Certificate(s) will be generated directly inside the configuration/ssl directory
  • usage: cert site1.internal site2.com *.site3.com .....

Usable inside docker container:

• git (if you need to incorporate ssh keys with git, use the configuration/ssh directory)
• curl
• wget
• net-tools (available commands: arp, hostname, ifconfig, netstat,... etc.)
• git fame # Git contributor stats
  • git fame -e --enum # Get Normal Counter on Surviving code (low accuracy)
  • git fame -ewMC --enum # Deep Counter on Surviving code (intra-file & inter-file modifier detector, file system independent) more calculation time
  • Check git fame -h command for command details
• owners # generate owners list (i.e for Github: owners | tee .github/CODEOWNERS)
• git-story # Animated Git story generator (check git-story -h for command details)

ToDo

• Tunnel support
• SupervisorD with PHP