/prestashop-flashlight

A docker based testing utility for PrestaShop

Primary LanguageShellMIT LicenseMIT

PrestaShop Flashlight logo

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 bootstraping 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 (coming soon)
  • 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:

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:

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

Environment variables

Variable Description Required Default value
PS_DOMAIN the public domain (and port) to reach your PrestaShop instance yes, unles using NGROK_TUNNEL_AUTO_DETECT N/A (example: localhost:8000)
NGROK_TUNNEL_AUTO_DETECT the ngrok agent base API url, to guess the tunnel domain of your shop yes, unless using PS_DOMAIN N/A (example http://ngrok:4040)
SSL_REDIRECT if enabled and using PS_DOMAIN, PrestaShop will redirect all inbound traffic to https://$PS_DOMAIN no false (example: true)
DEBUG_MODE if enabled the Debug mode will be enabled on PrestaShop no false
INSTALL_MODULES_DIR module directory containing zips to be installed with the PrestaShop CLI no empty string (example: /ps-modules)
INIT_SCRIPTS_DIR script directory with executable files to be run prior to PrestaShop startup no /tmp/init-scripts
POST_SCRIPTS_DIR script directory with executable files to be run after the PrestaShop startup no /tmp/post-scripts
INIT_SCRIPTS_USER the user running the executable files to be run prior to PrestaShop startup no www-data
POST_SCRIPTS_USER the user running the executable files to be run after the PrestaShop startup no www-data
INIT_ON_RESTART if enabled the PS_DOMAIN auto search and dump fix will be replayed on container restart no false
DUMP_ON_RESTART if enabled the dump restoration replayed on container restart no false
INSTALL_MODULES_ON_RESTART if enabled zip modules will be reinstalled on container restart no false
INIT_SCRIPTS_ON_RESTART if enabled custom init scripts will be replayed on container restart no false
POST_SCRIPTS_ON_RESTART if enabled custom post scripts will be replayed on container restart no false
ON_INIT_SCRIPT_FAILURE if set to continue, PrestaShop Flashlight will continue the boot process even if an init script failed no fail
ON_POST_SCRIPT_FAILURE if set to continue, PrestaShop Flashlight won't exit in case of script failure no fail
ON_INSTALL_MODULES_FAILURE if set to continue, module installation failure will not block the init process no fail
DRY_RUN if enabled, the run.sh script will exit without really starting a web server no false

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 admin@prestashop.com
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!

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 know about 8000 in our use case. Let's talk to 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:

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

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:

./lint.sh

Credits