PrestaShop

Streamline PrestaShop 9 Development: Your Ultimate Docker Setup Guide

Setting up a robust and efficient local development environment is the cornerstone of successful e-commerce projects. For PrestaShop developers, especially those working on custom modules, themes, or core modifications, a streamlined setup is not just a convenience—it's a necessity. At Migrate My Shop, we understand the critical role a stable development environment plays in successful migrations and upgrades.

A recent discussion on the PrestaShop forum, initiated by Knowband Plugins, highlighted an excellent approach to leveraging Docker for PrestaShop 9 local development. This method emphasizes isolation, reproducibility, and ease of management, offering significant advantages over traditional setups. Let's dive into how you can master PrestaShop 9 local development using Docker.

PrestaShop 9 docker-compose.yml file structure
PrestaShop 9 docker-compose.yml file structure

Why Docker for PrestaShop 9 Local Development?

The primary appeal of Docker lies in its ability to create isolated, disposable development environments. Imagine spinning up a complete PrestaShop instance with its database, making changes, testing thoroughly, and then easily discarding or resetting it—all without cluttering your host machine. This approach is particularly beneficial for:

  • Module and Theme Development: Rapidly test changes in a clean, consistent environment, ensuring your code works as expected across different setups.
  • Core Work: Experiment with PrestaShop core modifications without the risk of breaking your primary system.
  • Version Management: Effortlessly switch between different PrestaShop or PHP versions for compatibility testing or multi-project development.
  • Team Collaboration: Ensure all team members work with identical environments, eliminating "it works on my machine" issues.
  • Migration Testing: Create a sandbox to test PrestaShop migrations or upgrades before deploying to production, a service we frequently provide at Migrate My Shop.

This guide focuses on using the official PrestaShop Docker image with Docker Compose, providing a simple yet powerful stack tailored for local development, explicitly excluding production use cases.

Diagram illustrating Docker containers for PrestaShop 9 local development, showing a database container and a PrestaShop application container connected, with host machine volumes mounted for code editing.
Illustration: A visual representation of a Dockerized PrestaShop 9 local development environment, highlighting the separation of database and application containers and the host machine's interaction with mounted volumes.

Key Prerequisites and Setup Steps

Before you begin, ensure your system is ready:

  • Docker with Compose: Docker Desktop for Windows/macOS includes Compose. On Linux, the Compose plugin might require a separate installation.
  • One Free Host Port: Commonly 8080, but any available port will work.
  • PHP Version: For PrestaShop 9.2.0, PHP 8.1 to 8.5 is recommended. Docker Hub offers tags for this range.
  • Database: MySQL 5.7+ or MariaDB 10.2+ is required. MySQL 8.0 is a solid choice for modern development.

1. Choosing Your Image Tag

Docker Hub tags combine PrestaShop and PHP versions (e.g., prestashop/prestashop:9.2.0-8.4). Always pin specific versions instead of using latest to prevent unexpected changes and ensure reproducibility. The Docker Hub page's tag list is the most reliable source for available versions.

2. Create Your Project Folder and Database Service

Start by creating a project folder (e.g., my-prestashop-project) with a modules subfolder inside it. Then, create a docker-compose.yml file within your project folder. This file defines your services:

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: prestashop
      MYSQL_USER: ps_app
      MYSQL_PASSWORD: change_this_locally
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u $$MYSQL_USER --password=$$MYSQL_PASSWORD"]
      interval: 5s
      timeout: 4s
      retries: 12

Here, mysql:8.0 provides a modern database. MYSQL_RANDOM_ROOT_PASSWORD: "yes" ensures a secure, disposable root password, which you won't need to access directly. The ps_app user handles all shop connections, and the health check confirms its connectivity. Remember to replace change_this_locally with a strong, unique password for your local environment.

3. Add the PrestaShop Service and Volumes

Now, add the PrestaShop service below the database service in your docker-compose.yml, along with the global volumes block:

  prestashop:
    image: prestashop/prestashop:9.2.0-8.4
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:80"
    environment:
      DB_SERVER: db
      DB_NAME: prestashop
      DB_USER: ps_app
      DB_PASSWD: change_this_locally
      PS_INSTALL_AUTO: 1
      PS_DOMAIN: localhost:8080
      PS_DEV_MODE: 1
      PS_FOLDER_ADMIN: admin-dev
      ADMIN_MAIL: admin@example.com
      ADMIN_PASSWD: change_this_too
    volumes:
      - ps_data:/var/www/html
      - ./modules/mymodule:/var/www/html/modules/mymodule

volumes:
  db_data:
  ps_data:

Key environment variables:

  • DB_SERVER: db: Points to your database service.
  • PS_INSTALL_AUTO: 1: Skips the browser installer for automated setup.
  • PS_DOMAIN: localhost:8080: Tells PrestaShop its accessible domain.
  • PS_DEV_MODE: 1: Enables development mode for debugging.
  • PS_FOLDER_ADMIN: admin-dev: Renames the back office folder for better security.

Crucially, the ./modules/mymodule:/var/www/html/modules/mymodule line mounts a local folder into the container. This allows you to edit your module files directly from your host machine, with changes reflected instantly in the container—a massive time-saver for module and theme developers.

4. Start Your Stack

Navigate to your project folder in the terminal and run:

docker compose up -d

Monitor the PrestaShop container's logs during the initial setup:

docker compose logs -f prestashop

Give it a few minutes for the installation to complete.

5. Open Your Shop

Once healthy, access your PrestaShop instance:

  • Front Office: http://localhost:8080
  • Back Office: http://localhost:8080/admin-dev (using admin@example.com and change_this_too as credentials).

6. Confirm Module Folder Mount

Verify your module folder is correctly mounted:

docker compose exec prestashop ls /var/www/html/modules/mymodule

You should see the contents of your local mymodule folder. Edits made on your host machine will appear immediately in the container.

Advanced Development Tips & Best Practices

  • File Permissions: As highlighted by Alexandre Carette, if your mounted module can't write files, check its permissions on your host machine. Docker respects these permissions.
  • Console Commands: For PrestaShop CLI commands (e.g., clearing cache, enabling modules), use docker compose exec prestashop php bin/console prestashop:module enable mymodule.
  • Hummingbird Development: If you're building the new Hummingbird theme from source for PrestaShop 9, ensure you're using Node.js 24 and npm 11, as specified in the 9.2 announcement.
  • Resetting Your Environment: To start fresh, stop and remove containers and volumes: docker compose down -v. This will delete db_data and ps_data, giving you a clean slate.

Official Image vs. Laradock: Choosing Your Path

The method described above uses the official PrestaShop Docker image, which is ideal for a single, isolated PrestaShop instance. It installs PrestaShop directly and configures it via environment variables.

Alternatively, tools like Laradock provide a broader development environment, starting with Nginx, MySQL, and a workspace container. PrestaShop is then installed within the workspace (e.g., via composer create-project prestashop/prestashop .). Laradock is often preferred by developers managing multiple PHP projects on a single stack, offering more flexibility but also greater complexity.

Diagram showing the structure of a docker-compose.yml file for PrestaShop 9, illustrating services like 'db' and 'prestashop', their dependencies, ports, environment variables, and mounted volumes.
Illustration: A conceptual diagram of the docker-compose.yml file, detailing how different services (database, PrestaShop application) are defined, linked, and configured with environment variables and volume mounts for local development.

Troubleshooting Common Docker Hurdles

  • Port Already Allocated: If port 8080 is in use, change the left number in the ports line (e.g., "8081:80") and update PS_DOMAIN accordingly.
  • Redirect to Internal Address or Blank Page: Ensure PS_DOMAIN exactly matches what you type in your browser (e.g., localhost:8080).
  • Installer Can't Reach Database: Check docker compose logs db to ensure the database container is healthy. Verify that DB_USER in the PrestaShop service matches MYSQL_USER in the database service.
  • MySQL 8 Authentication/Charset Errors: Refer to the official Docker image troubleshooting notes for solutions involving the caching_sha2_password plugin or charset configuration.

Conclusion

Adopting Docker for PrestaShop 9 local development significantly enhances your workflow, offering unparalleled stability, reproducibility, and efficiency. Whether you're a seasoned developer or just starting, this setup empowers you to build, test, and innovate with confidence. A robust development environment is key to successful e-commerce operations, and it's a foundation we at Migrate My Shop advocate for all our clients, especially when planning complex migrations or upgrades.

Ready to optimize your PrestaShop development or considering a seamless migration to PrestaShop 9? Visit migratemyshop.com to learn how our expertise can support your e-commerce journey.

Share:

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools