prestashop / prestashop-flashlight

A docker based testing utility for PrestaShop

Spin up a PrestaShop testing instance in seconds!

PrestaShop Flashlight is fast: the PrestaShop installation wizard is run at build time, compiling the result to a single database dump. You will get all the content (catalog, orders...) of the usual PrestaShop development seed.

Supported architectures:

• linux/amd64 (aka x86_64)
• linux/arm64/v8 (aka arm64)

⚡ Disclaimer: this tool is provided with the sole purpose of bootstrapping a development or testing environment and is unsuitable for production.
If you're looking for a production grade image, please refer to https://github.com/PrestaShop/docker.

How to get PrestaShop Flashlight?

This project can be built locally anytime, but it's easier to use our pre-built Docker image available on the Docker Hub.

You may browse a wide variety of tags, including:

• latest
• nightly
• 1.7.8.11 if you want PrestaShop 1.7.8.11 with its recommended PHP version and tools
• 1.7.8.11-debian same as above, but shipped with Debian Linux (Alpine Linux is the default)
• 1.7.8.11-7.4 PrestaShop version 1.7.8.11 with PHP 7.4 and Alpine Linux
• php-8.1 to get the latest PrestaShop version recommending PHP 8.1

Some tags may not be built yet, feel free to fill an issue to request it.

Use

PrestaShop Flashlight can be used as a development environment, a CI/CD asset to build up a custom PrestaShop environment, or any use case you can think of. Following is a list of resources and examples to get you started:

• Basic example
• Nightly example
• Develop PrestaShop
• Develop a PrestaShop Module
• Custom init-scripts
• Custom post-scripts
• Ngrok tunneling
• Auto installation of modules
• Xdebug a store
• Develop a PrestaShop Theme (coming soon)
• Use in GitHub Action (coming soon)

PrestaShop Flashlight embeds nginx and php-fpm, however the MySQL server has to be provided separately. This can easily be achieved using docker compose: docker-compose.yml files are provided in examples.

Compatibility

PrestaShop Flashlight is based on the official compatibility charts:

• PrestaShop 1.6-1.7.x PHP compatibility chart
• PrestaShop 8.x PHP compatibility chart

You can check this implementation anytime in prestashop-version.json.

Environment variables

Variable	Description	Default value
PS_DOMAIN¹	the public domain (and port) to reach your PrestaShop instance	N/A (example: localhost:8000)
NGROK_TUNNEL_AUTO_DETECT²	the ngrok agent base API url, to guess the tunnel domain of your shop	N/A (example http://ngrok:4040)
DEBUG_MODE	if enabled the Debug mode will be enabled on PrestaShop	false
DRY_RUN	if enabled, the run.sh script will exit without really starting a web server	false
DUMP_ON_RESTART	if enabled the dump restoration replayed on container restart	false
INIT_ON_RESTART	if enabled the PS_DOMAIN auto search and dump fix will be replayed on container restart	false
INIT_SCRIPTS_DIR	script directory with executable files to be run prior to PrestaShop startup	/tmp/init-scripts
INIT_SCRIPTS_ON_RESTART	if enabled custom init scripts will be replayed on container restart	false
INIT_SCRIPTS_USER	the user running the executable files to be run prior to PrestaShop startup	www-data
INSTALL_MODULES_DIR	module directory containing zips to be installed with the PrestaShop CLI	empty string (example: /ps-modules)
INSTALL_MODULES_ON_RESTART	if enabled zip modules will be reinstalled on container restart	false
MYSQL_DATABASE	MySQL database name	prestashop
MYSQL_EXTRA_DUMP	extra SQL dump to be restored in PrestaShop	empty string (example: /tmp/foo.sql)
MYSQL_HOST	MySQL host	mysql
MYSQL_PASSWORD	MySQL password	prestashop
MYSQL_PORT	MySQL server port	3306
MYSQL_USER	MySQL user	prestashop
ON_INIT_SCRIPT_FAILURE	if set to continue, PrestaShop Flashlight will continue the boot process even if an init script failed	fail
ON_INSTALL_MODULES_FAILURE	if set to continue, module installation failure will not block the init process	fail
ON_POST_SCRIPT_FAILURE	if set to continue, PrestaShop Flashlight won't exit in case of script failure	fail
POST_SCRIPTS_DIR	script directory with executable files to be run after the PrestaShop startup	/tmp/post-scripts
POST_SCRIPTS_ON_RESTART	if enabled custom post scripts will be replayed on container restart	false
POST_SCRIPTS_USER	the user running the executable files to be run after the PrestaShop startup	www-data
PS_FOLDER	prestashop sources directory	/var/www/html
PS_PROTOCOL	if PS_PROTOCOL equals https the public URL will be https://$PS_DOMAIN	http (example: https)
SSL_REDIRECT	if enabled the public URL will be https://$PS_DOMAIN (if not using PS_PROTOCOL)	false (example: true)
XDEBUG_ENABLED	if enabled Xdebug will be enabled in PHP. See settings here: $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini	false (example: true)

Note:

• ¹required (mutually exclusive with NGROK_TUNNEL_AUTO_DETECT)
• ²required (mutually exclusive with PS_DOMAIN)

Back office access information

The default url/credentials to access to PrestaShop's back office defined in ./assets/hydrate.sh and are set to:

Url	{PS_DOMAIN}/admin-dev
Login	[email protected]
Password	prestashop

Exit codes

On error, PrestaShop Flashlight can quit with these exit codes:

Exit Code	Description
0	graceful exit, probably running dry mode or after a SIGKILL
1	reserved for nginx
2	Missing $PS_DOMAIN or $NGROK_TUNNEL_AUTO_DETECT
3	Ngrok domain cannot be guessed
4	Cannot find PrestaShop configuration file in $PS_FOLDER
5	SQL dump is missing
6	some module installation failed (with $ON_INSTALL_MODULES_FAILURE set to fail)
7	some init script failed (with $ON_INIT_SCRIPT_FAILURE set to fail)
8	some post script failed (with $ON_POST_SCRIPT_FAILURE set to fail)

Q&A

Does Flashlight support PrestaShop 1.6?

Partially yes. As there is no console within the sources, the modules cannot be automatically installed right now. Feel free to contribute!

Developing a module with RW (known Linux issue)

The develop-a-module example is provided as a local environment for a developer. At PrestaShop, we could successfully use it with Mac OSx and Windows, but due to the nature of the Docker implementation on Linux (no virtualization), we could not yet allow the module to write content from PrestaShop to the host. Will keep you posted here, feel free to suggest your ideas in this project issues.

Api calls within a docker network

Disclaimer: PrestaShop is sensitive to the Host header of your client, and can behave surprisingly. In fact, since the Multi-shop feature is available, you cannot just call any front controller from any endpoint unless you set the Host or the id_shop you are targeting.

Let's explain this subtle - rather mandatory - knowledge:

Assume you have a module installed and working properly, and your PS_DOMAIN configured on http://localhost:8000

> docker compose up -d
> curl -i 'http://localhost:8000/index.php?fc=module&module=mymodule&controller=myctrl'
HTTP/1.1 200 OK
some happy content here ...

Is working as expected. But what about the same request performed within the docker container?

> docker exec -t prestashop curl -i 'http://localhost:8000/index.php?fc=module&module=mymodule&controller=myctrl'
curl: (7) Failed to connect to localhost port 32000 after 5 ms: Couldn't connect to server

Indeed, this WON'T WORK, the container port is 80, only the host knows about 8000 in our use case. Let's talk about it:

> docker exec -t prestashop curl -i 'http://localhost/index.php?fc=module&module=mymodule&controller=myctrl'
HTTP/1.1 302 Found
Server: nginx/1.24.0
Date: Tue, 22 Aug 2023 08:53:22 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/8.1.22
Location: http://localhost:8000/

Damn! Do you know what's happening? PrestaShop cannot know which shop of its multi-shop configuration you are trying to talk to. Event with one shop, this won't be selected by default and fail with a redirect which cannot be resolved within our network configuration.

If you definitely know the Shop ID you are targeting, you can do this with success:

curl -i -H  'http://localhost:80/index.php?id_shop=1&fc=module&module=mymodule&controller=myctrl'
HTTP/1.1 200 OK
some happy content here ...

but the best way to perform this is to set the target Host in a header field:

curl -i -H 'Host: localhost:8000' 'http://localhost:80/index.php?fc=module&module=mymodule&controller=myctrl'
HTTP/1.1 302 Found
Server: nginx/1.24.0
Date: Tue, 22 Aug 2023 08:53:22 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/8.1.22
Location: http://localhost:8000/

or even better if you use a Nginx reverse-proxy to forward requests to prestashop within the internal docker network:

# so you can call "http://localhost:3000/prestashop/index.php" to reach your PrestaShop id_shop 1 with success
server {
  location /prestashop {
      resolver 127.0.0.11 ipv6=off valid=10s;
      resolver_timeout 10s;
      proxy_set_header Host "localhost:8000";
      rewrite /prestashop/?(.*) /$1 break;
      set $frontend "http://prestashop:80";
      proxy_pass $frontend;
  }
}

Contribute

This Project is under the MIT Licence, your contribution and new use cases are very welcome.

Build

Dependencies:

• jq
• Docker buildx

To build Flashlight for the latest PrestaShop version available:

./build.sh

Same but for a predefined PHP and PrestaShop version:

PS_VERSION=8.1.0 \
PHP_VERSION=8.1 \
TARGET_IMAGE=my-own-repo/testing:latest \
./build.sh

To get more documentation on the available build options, please consider reading the build.sh top file Available variables section.

Cross compiling for another architecture

Init buildx:

docker buildx create --name mybuilder --use --platform linux/amd64,linux/arm64

Then:

TARGET_PLATFORM=linux/amd64,linux/arm64 \
./build.sh

The OS_FLAVOUR defaults to alpine (see Alpine Linux) and SERVER_FLAVOUR to nginx (see Nginx).

For more documentation about available build variables, please see ./build.sh.

Lint

Requirements:

• shellcheck
• hadolint

./lint.sh

Credits

• https://github.com/PrestaShop/PrestaShop
• https://github.com/PrestaShop/performance-project
• https://github.com/jokesterfr/docker-prestashop
• https://github.com/PrestaShop/php-dev-tools

prestashop-flashlight's Issues

8M is not enough for most of the volumes

Requirement by @Thymotep, testing big zips is often cumbersome.
Adding 20M should be enough.

Idea: add opcache support

Example:

# RUN docker-php-ext-enable opcache
# RUN echo '\
#   opcache.interned_strings_buffer=16\n\
#   opcache.load_comments=Off\n\
#   opcache.max_accelerated_files=16000\n\
#   opcache.save_comments=Off\n\
#   ' >> /usr/local/etc/php/conf.d/docker-php-ext-opcache.ini

Would be an interesting feature to add, but like the Xdebug mode: with a default opt-out, and only a OPCACHE_SUPPORT=true env would enable it.

Add XDEBUG support

SMB team requires this to work on FlashLight.
Promoter: PrestaShop Corp.

ON_INSTALL_MODULES_FAILURE does not detect all modules installation errors

The command: php -d memory_limit=-1 bin/console prestashop:module --no-interaction install "$module" returns an exit status of 0 even when the module wasn't installed.

/var/www/html/bin # php -d memory_limit=-1 ./console prestashop:module --no-interaction install facebookconversiontrackingplus-master-32014-187311.zip
                                                                                                                             
  Cannot install module facebookconversiontrackingplus-master-32014-187311.zip. The module is invalid and cannot be loaded.  
                                                                                                                             
/var/www/html/bin # echo $?
0

The setting ON_INSTALL_MODULES_FAILURE=fail is ignored in this scenario.

Themes auto-install support

Like for module development, being able to automatically install themes would be a great improvement to get a fast live dev environment.

Latest tag should only stand for the recommended PHP version

The build.sh tagger takes "latest" when we build the latest version of PrestaShop with an "unrecommended" yet "compatible" version of PHP.

Example: PS_VERSION=8.1.3 PHP=7.3

This is not the expected behaviour.

Recommended PHP versions should also be used to provide Docker images on the dockerhub

A request from @Mikatux, recommended PHP versions are described here https://github.com/PrestaShop/prestashop-flashlight/blob/main/prestashop-versions.json, but these are not used yet to build images.

PrestaShop nightly image unavailable

Having an up-to-date nightly can be useful for at least:

• you can weekly run your tests on it, to detect any unexpected breaking changes with your module
• you can run daily E2E tests on the PrestaShop Core feature set

This suggest to rely on a webhook mechanism to trigger the prestashop-flashlight CI once a hook is emitted from the Core. Not sure how to make this happen, but any help is welcome.

The build.sh script should also be adapted to allow a build from the last nightly build available.

Add the ability to automatically switch the language

Languages pack can be modified in the back office, but it would be neat to be able to swap at bootstrap time from PrestaShop Flashlight environment vars.

@StephaneDecisy

Provide examples on how to generate a lot of content in the sql dump

Huge datasets often offer unexpected errors with your code, which might be inapropriate in some cases. To better tickle your SQL requests with such heavy environment, we can consider using an extra dump (already available)... But a better option would be to rely on a generation tool, plugged to prestashop-flashlight.

A proof of concept is probably not hard to come up with, let's see who reach the challenge first ;)

PrestaShop Core branch testing

As suggested by @MatShir, it could be nice to provide a quick way to perform integration testing of core branches directly on PrestaShop flashlight. For a matter of bootstrap speed.

This can easily be done with custom init-scripts, and such feature could be provided as an example in this repository. Once the nightly will be supported by flashlight this will be even more meaningful.

See #29.

Cross compilation does not work

At least from x86_64, building the sources with Node.js appears to fail on the aarch64 target.

A CI test is welcomed to assert no regression of this kind would come again.

Not blocking if you build flashlight for you own use (ie: if BUILDPLATFORM == TARGETPLATFORM).

[run.sh] sed failing to operate replace with some URLs

At runtime:

Attaching to prestashop-1
prestashop-1  | * Applying PS_DOMAIN (https://test.something-like.this.com) to the dump...
prestashop-1  | sed: bad option in substitution expression
prestashop-1 exited with code 1

@hschoenenberger just had this issue Today as well.

FreeType support for PHP gd

The GD extension can be shipped with some extra abilities, FreeType is one of them. https://www.php.net/manual/fr/function.imageftbbox.php is one function used within the PrestaShop Core, and which could be used by module developers as well.

Thank you @ga-devfront for your feedback.

As a complete development environment, PrestaShop Flashlight should also bring complete tools for testing, with FreeType support.

If any other extension or configuration was found missing, feel free to contribute to this project.

Add github-cli support

gh is a useful tool for many use-case, it's lightweight. Let's ship it in flashlight.

PrestaShop 1.6 does not support the console: no module auto-install can be performed yet

The PrestaShop console has been introduced by branch 1.7, but it is really handy when it comes to installing modules in many use cases.

PrestaShop Flashlight does not intend to backport features, nor fix security issues to any PrestaShop version in the nature. However for compatibility testing, extending this capability is likely to match CI/CD users eager at extending support of their modules to the maximum audience possible.

I suggest to copy, repack, and commit a light version of the console within the 1.6 Docker images of PrestaShop Flashlight. This can be done through the editing of the assets/patch.sh file, and removing the check made in ./assets/run.sh:

echo "Auto-installing modules with PrestaShop v1.6 is not yet supported";

I guess it is a very good "first issue" to take for anyone wanting to give a hand on this project. Thank you for your support!

Nightly CI hangs unexpectedly

Without any obvious reason, the github action process built to publish new images on Docker hub hangs 45mn, and timeout.

At this stage, no clear evidence of what's happening has been found.

Nginx client_max_body_size too low

Hello,
I am currently working with flashlight on themes as well as modules. However, when I try to add a theme from the BO which runs under Docker I encounter a major problem. Indeed, the nginx client_max_body_size is defined at 8MB while it is possible to have themes that can go up to 40MB, It is therefore impossible for me to add my themes.
I think it would therefore be good to increase this limit or pass it as a parameter.