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.
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.

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: 12Here, 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 -dMonitor the PrestaShop container's logs during the initial setup:
docker compose logs -f prestashopGive 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(usingadmin@example.comandchange_this_tooas credentials).
6. Confirm Module Folder Mount
Verify your module folder is correctly mounted:
docker compose exec prestashop ls /var/www/html/modules/mymoduleYou 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 deletedb_dataandps_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.

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
8080is in use, change the left number in theportsline (e.g.,"8081:80") and updatePS_DOMAINaccordingly. - Redirect to Internal Address or Blank Page: Ensure
PS_DOMAINexactly matches what you type in your browser (e.g.,localhost:8080). - Installer Can't Reach Database: Check
docker compose logs dbto ensure the database container is healthy. Verify thatDB_USERin the PrestaShop service matchesMYSQL_USERin the database service. - MySQL 8 Authentication/Charset Errors: Refer to the official Docker image troubleshooting notes for solutions involving the
caching_sha2_passwordplugin 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.