You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Peter Drinnan df4942c612 sds 1 month ago
.vscode typo fixed in installer shell scripts 1 month ago
config stable version 1 month ago
desktop-commands global update of db username to "user" 1 month ago
docker-image install gatsby globally within pslamp container 1 month ago
projects sds 1 month ago
.env.example stable version 1 month ago
.gitignore updated gitignore 1 month ago
.run.env init 2 months ago
README.md rename example sites 1 month ago
bash_aliases_examples.txt rename example sites 1 month ago
createSSLCert.sh fix for createcert 2 months ago
docker-compose.yml.example experimenting with gatsby and strapi 1 month ago
full_install.sh typo fixed in installer shell scripts 1 month ago
partial_install.sh typo fixed in installer shell scripts 1 month ago
prepareDockerConfigs.sh stable version 1 month ago
terminalcommands.sh.example added command to flush mysql volume 2 months ago
zprofile_examples.txt rename example sites 1 month ago

README.md

pslamp-docker

This repository contains all the necessary pieces to setup a local development environment with docker.

Repository Structure

The shell of the code is the docker-compose.yml file. It describes how to deploy the services, including a db. It is fairly simple and it really depend on all the other files in the repository.

Folder docker-image contains different verions of Dockerfile which is used to create a docker image with

  • php 7.x
  • apache
  • nodeJs
  • composer
  • adminer
  • portainer

This image also installs a db client and makes sure a script is executed when the container is started. This script (found in config/run.sh) is copied to the image and is set to be executed when the container boots up.

Last, folder config contains all the files required to build and deploy the services.

Special mention for the script config/run.sh is required. This script:

  • waits for the mysql service to become available
  • starts apache.

Requirements

To use this repository you first need to:

Getting Started

You can run an install the script from root folder. It will work for Mac and Linux. It docker and common development tools for web developers.

To run the script make it executable then cd into the root folder of this project and run it.

For a complete install of all dev tools run ./full_install.sh

For setting up just the docker repo folder run ./partial_install.sh

Step 1: Build the pslamp docker image

  1. First go to the root folder of this repository
  2. Then, from the comman line execute: docker-compose build --no-cache pslamp

Notice file docker-compose.yml contains a recipe to build the image.

This will take some time. It builds the image we’ll use for our deployment.

Step 2: Configure local SSL Certificates

  1. Install Mkcert
    • bash sudo apt update sudo apt install libnss-tools linuxbrew-wrapper brew install mkcert
    • Add /home/linuxbrew/.linuxbrew/bin to your $PATH Edit your $HOME/.profile file adding bash if [ -d "/home/linuxbrew/.linuxbrew/bin" ] ; then PATH="/home/linuxbrew/.linuxbrew/bin:$PATH" fi
  2. Create and install a local SSL Certificate Authority (CA) bash mkcert -install This allows mkcert to generate local SSL certificates that will be valide on your local machine. It might ask for your sudo password.
  3. Generate local SSL certificates for your local pslamp sites. bash ./createSSLCert.sh Note: you need to restart your browser for it to accept your local certificates as valid.

Step 3: Configure local system parameters

The containers are to be deployed locally on any OS so, it is expected that differences will occur. To accommodate for natural differences the following environment variables allow us to configure them.

REPOS_FOLDER : This is the folder in your local system that contains all the repositories : In the command line, go to that folder, and then execute pwd to find the value we have to set for this variable.

HOME_SSH : This is the folder createdy by ssh to keep your keys and other configuration. On Linux/Mac/WSL it is folder ~/.ssh, i.e. the .ssh folder on your home directory.

LOCALDEV_UID : This is your user id on your OS (Linux/Mac) it is required so that your code get the right access permissions inside the docker container : You can find it by executing: id -u : On Windows it is safe to use 1000 or 33

LOCALDEV_GID : This is your user groupd id on your OS (Linux/Mac) it is required so that your code get the right access permissions inside the docker container : You can find it by executing: id -g ${USERNAME} : On Windows use the same value we use for LARAVEL_UID

The easiest way to ensure these varialbles are set is to define them in an .env in the same folder as your pslamp-docker repo. You can use file .env.example as a template for this file.

In this document we’ll assume all these variables have been set, failing to do this would cause unintended consequences.

Step 4: Add Bash Functions to local host

Open the file named bash_aliases_example.txt at the root of this project and add the lines to ~/.bash_aliases for Linux or ~/.bash_profile for Mac.

Once complete open a terminal window and run the command to active:

# for mac source ~/.profile

# for linux source ~/.bash_aliases

Step 5: Launch containers

The environment variables we defined above are used by docker-compose to instantiate our containers.

Now we are ready to launch our containers. Simply execute:

docker-compose up -d

Note that the first part of the command sets the required environment variables (described above) and you can adjust them as necessary, and there are other ways to set them.

the -d flag will run the containers in the background.

  • execute docker-compose logs to see the logs.
  • execute docker-compose logs --follow to see the logs in real time.

What is going on?

Now docker is running 2 docker containers. They can talk to each other and you can access them in different ways. The most importan thing, though, is that you can no launch your browser and point to your local site, it should just work. You can also connect to the database as if it was running on your system. Simply point your client to localhost:3306.

How do I shut it down?

If you started it with docker-compose up -d, then you can stop it with docker-compose down.

Keep in mind that this will completely destroy the containers, so anything locally modified will be lost forever. However, there is hardly a need for that.

All the code folders are shared from your local system into the docker containers, so that is never lost.

The mysql storage is a volume created on your system, so that is not lost either.

pslamp container shell

If you need to, you can login into the pslamp container. This is useful when you need to check how things are going on inside the container, or when you need to run migrations or admin commands.

To open as shell session inside the pslamp container simply execute from the command line and in the folder of this repo:

docker-compose exec -u www-data pslamp bash

This will open a shell as the www-data user, which is the user that owns the code, php and apache services inside the container and it is mapped to match our account on our local system.

If you keep reading you’ll find another way to do this from a browser using portainer.

What can I do with this?

We have built this so that our sites, services are available for us, together with some tools, consistently for all developers. That is, we don’t need to worry about setting up the db server, the web server, the build and run stacks, everything is scripted and readily available.

You can modify your code directly on your computer, this code is shared with docker and, except for some corner cases, you can test your changes right away on your browser.

If you look at file docker-compose.yml, you will see a number of hostname mappings.

    extra_hosts:
      - "api.pslamp.localhost:127.0.0.1"
      - "pslamp.localhost:127.0.0.1"
      - "adminer.pslamp.localhost:127.0.0.1"

You can use these hostnames directly on your browser to reach the tools and services.

  • *api.pslamp.localhost provide web services for the apps
  • pslamp.localhost is the main pslamp site (web app)
  • adminer.pslamp.localhost is a web database client already configured to connect to your local db.
  • additionally,
    • you can reach the mysql service at localhost:3600 in case you don’t want to use adminer
    • you can visually see your docker containers on a browser by going to portainer at localhost:9001

stopping unused services

If there are containers you don’t want to keep running you can turn it off by

  1. go to the root folder of this repository
  2. execute docker-compose kill <service container> where <service container> is one of the following
    • portainer is the container that provides portainer.

The other 3 containers must run all the time for they provide the db service, the elasticsearch service and the web hosting service.

You can also use portainer to stop/start container other than portainer itself.

Portainer

Portainer, being a web ui tool, allow us to inspect our docker stack, logs, and even login into a container from the browser.

You will need to set a username and password the first time you use it. It is stored locally, so there is no way to recover it if you forget it, although it might be possible to force a reset.

Debugging PHP Code

The docker container includes xDebug and is ready to work with our IDE.

Xdebug configuration

You can tweak the Xdebug configuration on file docker-compose.yml:

The pslamp container definition has an environment variable for this purpose

- XDEBUG_CONFIG=remote_host=pslamp.docker.pslamp remote_port=9000 remote_enable=1 remote_autostart=1 default_enable=1 idekey=VSCODE remote_connect_back=1

Adjust it, in particular the idekey should match the key set in your IDE.

VSCode setup

On VS Code we can use the PHP Debug plugin, once installed we can go to the Debug panel (Ctrl+Shift+D).

  • Select Add configuration in the the dropdown at the top-right of the panel. it opens a file .vscode/launch.json with 2 configurations, we can modify the one that reads Listen for XDebug or create a new one. It has to look like this:
  "configurations": [
          {
              "name": "PSLAMP - Docker - XDebug",
              "type": "php",
              "request": "launch",
              "port": 9000,
              "pathMappings": {
                  "/var/www/pslamp-api": "${workspaceFolder}/pslamp-api",
                  "/var/www/pslamp-website": "${workspaceFolder}/pslamp-website"
              },
              "xdebugSettings": {
                  "max_data": 65535,
                  "show_hidden": 1,
                  "max_children": 100,
                  "max_depth": 5
              },
              "log": true
          },
          ...
  ]

After this, you can start debugging.