<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /guides/docker/local-development.md for this page in Markdown format</div>

Docker for Local Development

This guide will walk you through setting up and using the Docker-based local development environment for this project. It is structured to guide a beginner from installation and core concepts through to day-to-day project commands.

1. Prerequisites

Before you can do anything else, you must have Docker installed on your system.

• Docker Engine: Installation Guide
• Docker Compose: Installation Guide (Included with Docker Desktop for Mac and Windows).

2. Core Docker Concepts

To understand what the commands are doing, it helps to know a few key concepts.

What is a Container?

Think of a Docker container as a lightweight, self-contained box that holds everything an application needs to run: the code, its libraries, and its settings. This "box" isolates the application from your host machine and from other containers. For our project, we have separate boxes for the web server (Nginx), PHP, the database (MariaDB/Vitess), and so on. They all run in isolation but can communicate with each other over a private virtual network.

This approach provides a consistent environment everywhere. Because the application is bundled with its dependencies, the classic "it works on my machine" problem is eliminated.

How Docker Compose Manages Services

We use docker compose to manage all our service "boxes" as a single unit, called a stack. To make our environment predictable, we explicitly name our containers in the .yml files using the container_name property. This is why you will see the adveshop4- prefix in names like adveshop4-database.

3. Getting Started: Starting the Environment

The environment is managed by the ./compose.sh script, located in the .docker/integration/ directory. This unified wrapper script handles the complexity of loading the correct .yml files for different environments (Dev vs Prod), Database modes (MariaDB vs Vitess), and Redis modes.

To start the default development environment (MariaDB + Standalone Redis), navigate to the directory and run:

cd .docker/integration/
./compose.sh up -d

This command reads the configuration and starts all project services in the background (-d means "detached").

4. Checking the Environment

Now that the services are running, you need a way to see them.

How to See What's Running: docker ps

The single most useful command for day-to-day Docker work is docker ps. It lists all the containers currently running on your system.

Open a terminal and run it:

docker ps

You will see output like this (abbreviated):

CONTAINER ID   IMAGE                                 COMMAND                  STATUS         PORTS                               NAMES
_c01a..._      nginxinc/nginx-unprivileged:1.23      "/docker-entrypoint...."   Up 5 minutes   0.0.0.0:8080->8080/tcp              adveshop4-nginx-dev
_a23b..._      ecommercen/adveshop4-php_fpm_dev:1.0.0  "docker-php-entryp..."   Up 5 minutes   9000/tcp                            adveshop4-php-fpm-dev
_d45c..._      mariadb:10.6                          "docker-entrypoint.s..."   Up 5 minutes   3306/tcp                            adveshop4-database

The most important column here is NAMES. This is the actual, final name of the container. When a command in this guide requires a container name (like for docker cp), this is the name you need to use.

If you have many other Docker containers running, the docker ps list can get crowded. To see only the containers related to this project, you can use the ps command on our wrapper script:

./compose.sh ps

This will show you the same information, but filtered down to just the services defined in our project's compose files.

5. Services Overview

Here are the services that are started by the up command, along with their container names and how to access them.

Service	container_name in docker ps	Access / Purpose
nginx	adveshop4-nginx-dev	The web server: http://localhost:8080
php-fpm	adveshop4-php-fpm-dev	Processes all PHP code.
database	adveshop4-database	The Database server (defaults to MariaDB).
redis	adveshop4-redis	The Redis server for caching.
phpmyadmin	adveshop4-phpmyadmin	Web UI for the database: http://localhost:8081
redisinsight	adveshop4-redisinsight	Web UI for Redis: http://localhost:5540
php-cli	adveshop4-php-cli-dev	For running command-line scripts.
node-cli	adveshop4-node-cli	For running NPM and Node commands.

6. Using the Environment: Day-to-Day Operations

Viewing Logs

One of the first things you'll do when troubleshooting is check the logs. You can view a real-time stream of logs for any service.

# Follow the logs of the php-fpm service in real-time
./compose.sh logs -f php-fpm

# View the last 100 lines of logs from the database service
./compose.sh logs --tail=100 database

Running CLI Commands

You can run commands inside a container in two main ways: as a one-off command, or by opening an interactive shell.

One-off Commands

This is the most common way to run scripts like Composer or database migrations.

PHP / Composer / Migration commands:

# Install composer dependencies
./compose.sh exec php-cli composer install

# Run database migrations
./compose.sh exec php-cli php migrator.php migrate

# Run a specific seeder
./compose.sh exec php-cli php migrator.php seed:run --seed=YourSeederClassName

# Run an adveshop cli command 
./compose.sh exec php-cli php cli.php hashImages

Node.js / NPM commands:

./compose.sh exec node-cli npm install
./compose.sh exec node-cli npm run dev

Getting an Interactive Shell

Sometimes you need to explore a container's filesystem or run multiple commands. You can get an interactive shell (like bash or sh) inside a container for this purpose.

# Get a shell inside the php-cli container
./compose.sh exec php-cli sh

Once you run this, your terminal prompt will change, indicating that you are now "inside" the container. You can run commands like ls -la, pwd, env, and cd to look around. This is incredibly useful for debugging file paths or permissions.

To leave the container and return to your normal terminal, simply type exit and press Enter (or Ctrl+D).

Importing a SQL Database

If you have a SQL database export (e.g., dump.sql), you can import it directly. Note that we refer to the service as database now.

cat /path/to/your/dump.sql | ./compose.sh exec -T database mysql -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"

Alternatively, you can use docker cp to copy the file in first, a useful general-purpose technique to know.

# 1. Copy the file into the running container
docker cp /path/to/your/dump.sql adveshop4-database:/tmp/dump.sql

# 2. Exec into the container to import the file
./compose.sh exec database bash -c "mysql -u\"$MARIADB_USER\" -p\"$MARIADB_PASSWORD\" \"$MARIADB_DATABASE\" < /tmp/dump.sql"

Advanced Usage: Switching Modes

The compose.sh script supports environment variables to switch backend modes.

Run with Vitess (MySQL compatible sharding middleware):

DB_MODE=vitess ./compose.sh up -d

• Note: In Vitess mode, the database service is still named database, but runs the vitess/vttestserver image.

Run with Redis Cluster:

REDIS_MODE=cluster ./compose.sh up -d

• Note: This enables the Redis Cluster configuration (defaults to Standalone if omitted).

Run in Production Simulation Mode:

COMPOSE_ENV=prod ./compose.sh up -d

Xdebug and PHPStorm integration

To debug PHP code using Xdebug and PHPStorm, follow these steps:

1. Press Ctrl+Alt+S (or Cmd+, on Mac) to open the Settings/Preferences dialog in PHPStorm.
2. Navigate to PHP.
3. Click on the ... button next to the CLI Interpreter dropdown.
4. Click the + button to add a new interpreter, and select From Docker, Vagrant, VM, Remote....
5. Choose Docker Compose from the left sidebar.
6. For the configuration files, you must select the files used in the default stack:
   • ./.docker/integration/web-dev.compose.yml
   • ./.docker/integration/compose.yml
   • ./.docker/integration/dev.compose.yml
   • ./.docker/integration/tools.compose.yml
   • ./.docker/integration/backend-db-mariadb.compose.yml (Note: Select this for standard MariaDB dev)
7. Set the service to php-cli.
8. Click OK to save the interpreter.
9. Then navigate to PHP > Debug.
10. Ensure the Debug port is set to 9003 (the default for Xdebug 3).
11. Click Apply and OK to save your settings.
12. Then in PHP > Servers add a new server with the following settings:
    • Name: localhost (or docker, or whatever you prefer)
    • Host: localhost
    • Port: 8080
    • Use path mappings: Map the project's root to /usr/local/var/www/html.

Stopping the Environment

Once you're done working, you can stop the services to free up system resources.

# Stop all the services
./compose.sh down

# Stop services AND remove data volumes (for a fresh start)
./compose.sh down -v