Configuration

To obtain a sample configuration file, please run this command in a Composer-enabled project’s folder, once Linux for Composer has been installed:

$ php vendor/bin/linuxforcomposer.phar docker:run start

You will automatically initialize the project with the following default configuration:

{
    "name": "linuxforphp/linuxforcomposer",
    "description": "A Composer interface to run 'Linux for PHP' Docker containers, Dockerfiles or docker-compose files.",
    "single": {
        "image": {
            "linuxforcomposer": {
                "php-versions": [
                    "7.4",
                    "7.3",
                    "7.2"
                ],
                "script": [
                    "echo '<?php phpinfo();' > /srv/www/index.php",
                    "lfphp --mysql --phpfpm --apache"
                ],
                "thread-safe": "false"
            },
            "dockerfile": {
                "url": "",
                "container-name": "",
                "username": "",
                "token": ""
            }
        },
        "containers": {
            "modes": {
                "mode1": "detached",
                "mode2": "interactive",
                "mode3": "tty"
            },
            "ports": {
                "port1": [
                    "7474:80",
                    "7373:80",
                    "7272:80"
                ],
                "port2": [
                    "13306:3306",
                    "13307:3306",
                    "13308:3306"
                ]
            },
            "volumes": {
                "volume1": "",
                "volume2": ""
            },
            "persist-data": {
                "mount": "false",
                "root-name": "",
                "directories": {
                    "directory1": "",
                    "directory2": "",
                    "directory3": ""
                }
            }
        }
    },
    "docker-compose": {
        "url": "",
        "username": "",
        "token": ""
    },
    "lfphp-cloud": {
        "account": "",
        "username": "",
        "token": ""
    }
}

Linux for Composer has three main modes:

  • Single mode
  • Docker Compose mode
  • Linux for PHP Cloud mode

Only one of these modes can be used at one time.

When using the single mode, one must configure the image that should be used or built, and the containers that should be spun up.

The image can be configured through the image setting, and by using the linuxforcomposer standard mode, which uses Linux for PHP images in the background, or by using the dockerfile mode, which uses any of the images that you can find in the Docker Hub repositories. The dockerfile mode has precedence over the linuxforcomposer mode.

Note

For more information on configuring the linuxforcomposer mode, please see the Linux for Composer Mode section.

Since the dockerfile mode has precedence over the linuxforcomposer mode, one can keep all of the linuxforcomposer configurations intact by simply adding a dockerfile configuration, which will cause the linuxforcomposer configurations to be totally ignored. This is useful when spinning up an ad hoc image to quickly test something in a project’s code base.

Note

For more information on configuring the dockerfile mode, please see the Dockerfile Mode section.

Once the image is configured, the containers must be configured by using the containers setting. In this section, it is possible to configure the modes, ports, volumes and mount points for each container.

Note

For more information on configuring the containers setting, please see the Containers section.

When not using single mode, but when using the docker-compose mode instead, one must give the URL of a Git repository which contains a valid docker-compose.yml file in its root folder. Private repositories are also supported, but require that a username and an access token be given in this section of the linuxforcomposer.json file.

Note

For more information on configuring the docker-compose mode, please see the Docker Compose Mode section.

Finally, when not using either of the previous modes (single or docker-compose), but when using the lfphp-cloud mode in their place, it is possible to set up an automatic deployment of a project to the Linux for PHP Cloud, by configuring the account name, the username, and the public access token to a valid account.

Note

For more information on configuring the lfphp-cloud mode, please see the Linux for PHP Cloud Mode section.

For more details on how to get a Linux for PHP Cloud account, please see the Linux for PHP Cloud Services website.

Single Mode

In single mode, Linux for Composer will either use a Linux for PHP image, or an image that will be built using a Dockerfile. Once the image is ready, Linux for Composer will spin up one or more containers according to the options given in the Containers setting.

Image

The image section configures Linux for Composer to use and/or build an image. One must choose between the Linux for Composer Mode or Dockerfile Mode mode.

Note

The dockerfile mode has precedence over the linuxforcomposer mode.

Linux for Composer Mode

The main configuration settings for the linuxforcomposer mode are:

PHP Versions

php-versions (Required - Default: none)

A list of the available pre-compiled versions can be found in the Linux for PHP repository on Docker Hub.

If many versions are chosen at once, Linux for Composer will start a detached container for each chosen version.

If you wish to obtain an interactive shell, enter /bin/bash in the script section (see Scripts) and do not ask for the ‘detached’ mode in the modes section (see Modes).

Finally, if you enter a version number like 8.0 (without the ‘dev’ part), Linux for Composer will COMPILE the latest version from source!!! Now, that’s really bleeding edge, isn’t it?

Scripts

script (Optional - Default: ‘lfphp’)

You can enter any command that you wish to execute as soon as the Linux for PHP container has finished starting. The most common ones are ‘lfphp’ and ‘/bin/bash’. But, you could also execute a PHP script directly or launch one of the recipes from the Linux for PHP documentation. You may enter as many commands as you need, as long as you enter one command per line of the script setting.

For example, to install Drupal automatically, you could enter:

"lfphp-get cms drupal testapp"

Another example would be to install Laravel:

"lfphp-get php-frameworks laravel testapp"

And, then, to start the LAMPP stack only:

"lfphp --mysql --phpfpm --apache"

Thread-Safety

thread-safe (Optional - Default: ‘false’)

It is possible to run a Zend thread-safe (‘true’) or a non-thread safe (‘false’) version of PHP.

Dockerfile Mode

dockerfile (Optional - Default: none)

When configuring the dockerfile mode, one must give the url of the Dockerfile that is to be used, and a name (container-name) to the image and its subsequently-created container. The file’s URL can be local (path) or remote (http/https protocols only). If a remote Dockerfile requires authentication, it is possible to add a username and an access token to access a private repository, for example.

[...]

"dockerfile": {
    "url": "Dockerfile",
    "container-name": "specialproject",
    "username": "",
    "token": ""
}

[...]

Or,

[...]

"dockerfile": {
    "url": "https://example.com/repo/Dockerfile",
    "container-name": "specialproject2",
    "username": "user1",
    "token": "roviquerhoqiuerhvoqierbvoi"
}

[...]

Note

Please make sure cURL and Git are available on your system when trying to access remote files.

Containers

The main configuration settings for the containers section are:

Modes

modes (Optional - Default: detached mode)

There are three possible modes when running Docker containers with Linux for Composer:

  • Detached
  • Interactive
  • TTY

Whenever, you ask for the detached mode, it will take precedence over any other mode that you ask for in the linuxforcomposer.json file.

Note

For more information on Docker modes, please read the Docker documentation.

Ports

ports (Optional - Default: none)

You can share ports from the host system with your containers.

If you enter many port mappings for each shared port, Linux for Composer will share each mapping with one container in the order they were given. For example, ‘port1’ contains two mappings (8181:80 and 8282:80) and so does ‘port2’ (13306:3306 and 13307:3306). The first element of each mapping (8181:80 and 13306:3306) will be given to container 1, which corresponds to the first given PHP version in the php-versions section (see PHP Versions). The second element of each mapping (8282:80 and 13307:3306) will be given to container 2.

Volumes

volumes (Optional - Default: none)

You can share volumes between the host and your containers.

Note

Each volume will be shared with each and every container.

Linux/Unix/Mac users can insert Bash environment variables in this part of the JSON file. For example, you can share your current working directory with your containers by entering: “${PWD}/:/srv/www”. This will make your working directory available to the web server inside the Linux for PHP container.

On Windows 10 (PowerShell), please share the volume by using the following format:

"c:/Users/test:/srv/test"

On Windows 8 (Bash), please use the following format:

"/c/Users/test:/srv/test"

Note

Windows users must make sure to turn volume sharing on in the Docker settings.

Persist Data

persist-data (Optional - Default: false)

You can persist data by using Docker volumes and mounting them inside a container or sharing them between containers.

To mount Docker volumes to persist data from inside the container, one must set the mount setting to true, give a root name to the mounted volumes (we recommend setting it to the unique name of the project), and giving the names of the container’s directories that should be persisted. For example, one could persist the container’s ‘/srv’ folder like so:

[...]

"persist-data": {
    "mount": "true",
    "root-name": "unique_name_of_my_project",
    "directories": {
        "directory1": "/srv",
        "directory2": "",
        "directory3": ""
    }
}

[...]

This will instruct Linux for Composer to create a Docker volume with the name unique_name_of_my_project_srv and to share it with the container(s) created in the Linux for Composer Mode, or the container created in the Dockerfile Mode.

Upon creation of the volume, Linux for Composer will sync the new volume with the data that it will find in the designated directory.

Note

Windows containers are still NOT supported as of version 2.0.0 of Linux for Composer.

Docker Compose Mode

docker-compose (Optional - Default: none)

When configuring the docker-compose mode, one must give the url of the Git repository that has the main docker-compose.yml file in its root folder. The repository’s URL can be local (path) or remote (Git supported protocols only). If the remote repository requires authentication, it is possible to add a username and a token to access the repository.

[...]

"docker-compose": {
    "url": "asclinux-docker-compose",
    "username": "",
    "token": ""
},

[...]

Or,

[...]

"docker-compose": {
    "url": "https://github.com/andrewscaya/asclinux-docker-compose",
    "username": "",
    "token": ""
},

[...]

Note

Please make sure cURL and Git are available on your system when trying to access remote files.

Linux for PHP Cloud Mode

lfphp-cloud (Optional - Default: none)

When configuring the lfphp-cloud mode, one must give the name of the account, the username and the public access token of the Linux for PHP Cloud Services for the account that should to be used.

[...]

"lfphp-cloud": {
    "account": "johnsmithexamplecom1",
    "username": "john.smith@example.com",
    "token": "rnvaernlaiurnaliurnfgalriunvaernveiruneirug"
}

[...]

Note

Not all Linux for Composer settings are available on all Linux for PHP Cloud hosting plans. For more information, please see the Linux for PHP Cloud Services website.