README

Joomlatools Server

Cloud Native development environment for Joomla

Welcome to the Joomlatools Server codebase, our home-grown cloud native development environment for Joomla CMS, Wordpress and Joomlatools Pages.

What is Joomlatools Server?

Joomlatools Server is Docker container that is specially tailored for developing websites with Joomla CMS and Joomlatools Pages and is supported on macOS, Linux, and Windows (via WSL2).

It offers support for both Joomla 3 and 4 and can be used as a local/remote development environment. You can run it locally using Docker Desktop, or remotely using Gitpod.

Getting started

Installation

Getting started is very easy, first you need to install the source code on your local machine or create a new Git repo (in case you want to use Gitpod).

Via Download

The easiest way to get the code is to just download it. Click the code button and select Download Zip or use the following terminal command:

curl https://github.com/joomlatools/joomlatools-server/archive/refs/heads/master.tar.gz | tar -xz

Via Composer

You may also download Joomlatools Server by issuing the Composer create-project command in your terminal:

composer create-project joomlatools/server [directory] --stability dev

For more info: https://getcomposer.org/doc/03-cli.md#create-project

Via Clone

You can also clone the repository using Git by issueing the following command in your terminal:

git clone https://github.com/joomlatools/joomlatools-server

For more info: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository

Via Fork

Finally you can also fork the repository through Github, this can only be done through the Github user interface. For mor information: https://docs.github.com/en/get-started/quickstart/fork-a-repo#fork-an-example-repository

Using your own IDE

Make sure you have Docker Desktop installed and local installation of this repo. Go to the root directory of your installation and in the terminal and execute following command:

docker compose up

Using Gitpod IDE

Gitpod provides a super simple way to develop with Joomlatools Server using VSCode, straight from the browser. To get started make sure you have a clone or fork this repo, Gitpod offers support for GitHub, GitLab or Bitbucket and either:

Install the Gitpod Chrome or Firefox extension and click the Gitpod button in the toolbar.
Go to http://gitpod.io#[my-repo-url-goes-here]

You can find all the documentation for Gitpod here: https://www.gitpod.io/docs/

Gitpod Demo: If you want to give this repo a spin in Gitpod, just click this button to launch Joomlatools Server in Gitpod and automatically install the latest version of Joomla.

Architecture

Joomlatools Server runs applications as a multi-process Docker container. The processes are supervised using S6 overlay. While init systems like supervisord are better known, s6 is powerful, lightweight, easy to use, and plays nicely with docker (e.g. avoiding the pid 1 / zombie problem).

Each application is build on the joomlatools-server base image. It contains following:

Optional

MySQL 8.0

Tools

Multi-process Docker

One of the oft-repeated Docker mantras is "one process per container". There's nothing inherently bad about running multiple processes in a Docker container. The more abstract "one thing per container" is our policy - a container should do one thing, such as "run a chat service" or "run gitlab." This may involve multiple processes, which is fine.

The other reason image authors shy away from process supervisors is they believe a process supervisor must restart failed services, meaning the Docker container will never die.

This does effectively break the Docker ecosystem - most images run one process that will exit when there's an error. By exiting on error, you allow the system administrator to handle failures however they prefer. If your image will never exit, you now need some alternative method of error recovery and failure notification.

Our policy is that if "the thing" fails, then the container should fail, too. We do this by determining which processes can restart, and which should bring down the container. For example, if cron or syslog fails, your container can most likely restart it without any ill effects, but if ejabberd fails, the container should exit so the system administrator can take action.

Our interpretation of "The Docker Way" is thus:

Containers should do one thing. Containers should stop when that thing stops.

and the S6 init system is designed to do exactly that! Joomlatools Server still behaves like other Docker images and fit in with the existing ecosystem of images.

Composer

An application only contains a single composer /vendor directory which contains all PHP libraries used by the application libraries, sites and services. The /vendor directory is located in /srv/www/vendorand composer installation happens during the Docker image build phase.

Composer requires are being handled in 2 stage

1. During image build

With delay during ONBUILD, the base defines the minimal composer requires and the app that extends from base can define additional requires.

The Composer Merge Plugin is used to merge composer.json files from following locations:

/srv/www/config/composer/*.json
/var/www/composer.json
/srv/www/services/composer.json
/var/www/services/composer.json
/srv/www/sites/composer.json
/var/www/sites/composer.json

During image build, when Composer is run it will parse these files and merge their configuration settings into the base configuration. This combined configuration will then be used when downloading additional libraries and generating the autoloader.

2. During container run

If the app is running in development mode, APP_ENV = development, composer will be re-run. This allows to update dependencies and install require-dev dependencies without needing to rebuild the container or trigger composer manually. To make composer install dev dependencies add COMPOSER_NO_DEV=0 to you .env file or runtime environment.

composer.lock

If the application contains a /var/www/compooser.lock file composer will run composer install to install the specific versions of the libraries, if there is no composer.lock, it will run composer update to install the latest versions of the libraries.

If no composer.lock is provided the generated composer.lock is copied to /var/www/composer.lock to make it easy to commit it in the repo. Removing an existing lock file ensure the dependencies are updated.

opcache preload

By default the complete /vendor directory is preloaded in opcache unless APP_PRELOAD is disabled. To ignore a specific directory or file paths from being preloaded add a /var/www/config/opcache/preload_ignore.php file that returns an array of file paths relative to .../vendor to be ignored.

<?php
return [
    '/path/to/file',
];

Environment

The following is a list of application environment variables. Defaults are provided (or generated in case of APP_APIKEY and APP_NONCE) for each except if not provided

APP_NAME=jt-base The application name (default)
APP_ENV=production The application environment (default)
APP_USER=www-data The application user (default)
APP_ROOT=/var/www Location of the Apache root (default)
APP_DATA=/srv/www Location of the common code, /vendor etc. (default)
APP_VOLUME=/mnt/www Location of the persistent storage (default)
APP_PRELOAD=on Defines if opcache is preloaded from APP_DATA (default)
APP_CACHE=on Globally enable the application cache (default)
APP_DEBUG=off Globally enable application debug mode (default)
APP_HTTP=8080 External HTTP port the app is listening on (default)
APP_HTTP=8443 External HTTPS port the app is listening on (default)
APP_APIKEY= Bearer authentication token (generated if not provided)
APP_NONCE= Random number specific for the application (generated if not provided)

A complete list of all environment variables can be found in .env.default

Endpoints

The server provides following default HTTP(s) endpoints

Status

http://localhost:8080/__ping (php-fpm ping, local only)
http://localhost:8080/__status-php (php-fpm status, local only)
http://localhost:8080/__status-apache (apache status, local only)

Info

http://localhost:8080/__info/php-info
http://localhost:8080/__info/php-apc
http://localhost:8080/__info/php-fpm
http://localhost:8080/__info/php-opcache
http://localhost:8080/__info/php-xdebug (only if xdebug is enabled)

Documentation

You can find all the documentation for Joomlatools Server in the wiki. Happy coding!

Contributing

Joomlatools Server is an open source, community-driven project. Contributions are welcome from everyone. We have contributing guidelines to help you get started.

Contributors

See the list of contributors.

License

Joomlatools Server is open-source software licensed under the AGPLv3 license.

Community

Keep track of development and community news.

Follow @joomlatoolsdev on Twitter
Read the Joomlatools Developer Blog
Subscribe to the Joomlatools Developer Newsletter

⬆ Back to Top

joomlatools / server

Maintainers

Details