About | Features | Quick Start | Settings | Development | Localhost SSL | Composer | MySQL | Node | XDebug | Contributing | License
The Docker4LAMP project is intended to be a minimal but effective Docker based LAMP(Linux,Apache,MySQL,PHP) environment
It is intended to provide everything needed to have a structured development LAMP stack up and running on your workstation with a project layout in place that will allow you to iteratively develop a modern PHP application
- PHP 8.012
- Apache 2
- xdebug-3.1.1 (and documentation for connecting the Visual Studio Code debugger to the container)
- MySQL8
- PhpMyAdmin running by default on port 8080
- A mkcert container that generates certs for a dev domain
- A Node container for running npm and yarn
- Allowance for customization of mysql, php and apache configuration files
- Composer installed in the Server container
- A simple .env file that handles container naming, allowing for multiple unique container setups and port changes through simple text edits
- A preconfigured place to put project development files, that can support modern front-controller framework based applications
- essential documentation
By default your environment is set to provide PHP 8 and MySQL 8. It includes the official phpMyAdmin:latest docker environment for quick web interface access to the MySQL server, and is configured with version 3.x of xdebug, in a configuration that is tested and known to work with VSCode, and should work with other popular editors that support xdebug.
By default your development environment will be available at http://localhost and the phpMyAdmin server will be available at http://localhost:8080. These host ports are documented and can be easily changed in the top level .env file used by docker.
# Get Docker4LAMP git clone https://github.com/gizmola/docker4lamp
Most of the default settings should not need to be changed for your development environment. Change the APP_NAME variable to reflect the name of your new development project. This name is used to create the container names.
In most cases you don't need to change any of the defaults, as this is a development environment running on your workstation!
# /docker4lamp .env file. APP_NAME=your_project
APP_NAME is the base for container names for your project. Set it to something meaningful to avoid conflicts if you want to use docker4Lamp on multiple projects. This setting also helps you see which containers and images are part of your project.
TLD is the "Top Level Domain" used for the development certificate. It defaults to "test". This is the recommended/reserved TLD for local development domains and will not conflict with any production domains or DNS resolution. Only change this if you are sure you know what you are doing.
-
Keep in mind that the container names, database users and names are all created when the containers are first built. If you do want to change any defaults, be sure to edit the .env file before your first docker-compose up
-
If you intend to run multiple docker4lamp projects simultaneously, you will have to change the apache and phpmyadmin ports.
-
Switching between projects by using docker-compose up/down doesn't require any changes other than different APP_NAME settings.
-
Once the database is created, if you make changes to the database settings in the .env file, you will have to remove the database container and it's related volume in order to reinitialize the database container. You will lose any data you created if you remove the volume.
# Start the container docker-compose -d up
- Stop your containers using docker-compose down
- Remove the docker4lamp/.git directory.
- Optionally, rename the docker4lamp directory to a project name of your choosing
- start adding code, and/or packages with composer/composer.json
- Add your docker4lamp project to git
docker4compose uses the mkcert project to generate valid SSL certificates for your docker4lamp environment. This relieves you of having to install and run mkcert yourself, or reconfiguring the apache vhost.
All you need to do is retrieve the root cert from the container and install it in your workstation's local certificate store.
By default, the cert will allow for valid SSL access to *.APP_NAME.test
- The /cert directory is designed for you to keep a locally accessible copy of the generated certs
- Step #1: Copy the certs from the container
docker cp APP_NAME-mkcert:/root/.local/share/mkcert/ ./cert/
- Step #2: Install the root cert on your workstation
For Mac/OSX:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./cert/mkcert/rootCA.pem
For Windows: NOTE: You must be in a shell that was Run as Administrator!
certutil.exe -addstore root ./cert/mkcert/rootCA.pem
- Step #3: Add an entry to your /etc/hosts file for your dev domain. Assuming that your APP_NAME is "d4lprjct": If you are using windows the hosts file is located at c:\Windows\System32\Drivers\etc\hosts. You must open it with an editor that was "Run as Administrator" in order to save it.
127.0.0.1 d4lprjct.test www.d4lprjct.test
_Your browser should see your development server as valid when you open https://www.d4lprjct.test
By default Firefox does not trust root certs installed in the operating system. You can work around this using Mozilla's documentation.
Your code goes into the docker4lamp/project directory. Don't change the name of this directory unless you are clear on changes you would need to make to the apache and debug settings
docker4LAMP assumes you will be developing a front controller style app, with the webroot set to the project/ public directory
You can verify the names of your containers from your workstation by running
docker ps
Check the name column of the output. The Apache/PHP container will have a name like: your_project-server
You will substitute the server container name for your project, shown in the name column from the docker ps command
Access the container using Docker exec:
# connect as user www-data docker exec -it -u www-data:www-data -w /var/www/html/project **APP_NAME**-server /bin/bash
Once you are exec'd in the container you can run composer. This example will create a project composer.json and install the monolog component library
# Example composer require monolog/monolog
docker4lamp creates a database with the same name as your APP_NAME variable.
- hostname: db
- database: APP_NAME
- username: admin
- password: secret
These settings are used by phpMyAdmin to connect to your database. The docker network allows the php/apache server to connect to the database using the hostname db
These credentials can be used with mysqli or PDO to configure the database for development use. docker4LAMP was designed so that you can simply use the database and user created for you.
<?php
try {
$pdo = new \PDO(
'mysql:host=db;dbname=your_project;charset=utf8mb4', 'admin', 'secret',
array(
\PDO::ATTR_EMULATE_PREPARES => false,
\PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION
)
);
Echo "Connected Successfully";
} catch (\PDOException $e) {
throw new \PDOException($e->getMessage(), (int)$e->getCode());
}
If you want to change the defaults, edit the username, password, database settings in the .env file.
If you want to add additional databases, users etc. use docker to connect to the mysql container with docker exec. The mysql container will be named APP_NAME-database. The example below assumes APP_NAME=your_project
# root password: root_secret docker exec -it your_project-database mysql -u root -p your_project
The node service is already configured to create files and modules inside your project directory. It provides a way to integrate your react,vue,sass etc. components without having to install node modules and components on your local server. You can run these tools when you need them.
One excellent way of integrating javascript/scss is to use the symfony webpack encore package.
The ideal way to use the docker4lamp node service is to execute docker-compose run --rm node .... when you need yarn or npm.
Keep in mind, that the node service is not intended to persist, so make sure you use the --rm flag, or you will create new containers filling up your system.
To demonstrate use of the Node container, here is a simple howto that installs the node sass compiler.
- under project create an src/scss directory. Your sass files will go here.
- under the public directory create a css directory. The sass compiler will place the file here.
- create the file src/scss/main.scss
- Add some simple scss code like this:
$blue: blue;
body {
background: $blue;
}
- Install and configure the sass compiler
# Example: Install Yarn and add the SASS compiler docker-compose run --rm node yarn install # This makes your package.json file. Complete the prompts as you prefer docker-compose run --rm node yarn init # Install sass with the -D flag for development dependency docker-compose run --rm node yarn add sass -D # Run the sass compiler and watch for changes docker-compose run --rm node yarn sass -w src/scss:public/css
The sass compiler will create /public/css/main.css as well as main.css.map and will continue to watch for changes you make to /src/scss/main.scss
The base server image includes XDebug, as well as a preconfigured xdebug.ini in the server/php/conf.d directory
To debug with VSCode, you must install the PHP Debug Extension by Felix Becker
A verified working VSCode launch.json is included below:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Xdebug for Docker",
"type": "php",
"request": "launch",
"port": 9003,
//"stopOnEntry": true,
//"log": true,
"pathMappings": {
"/var/www/html/project": "${workspaceFolder}/project"
}
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9003
}
]
}
Copyright (c) 2021-2022 David Rolston