Installation Using Docker Desktop on macOS¶

This guide covers building new projects based on Shopsys Platform. If you want to contribute to Shopsys Platform itself, you need to install the whole shopsys/shopsys monorepo. Take a look at the article about Monorepo for more information.

This solution uses Mutagen (for relatively fast two-way synchronization of the application files between the host machine and Docker volume).

Requirements¶

• GIT
• PHP
  • At least version 8.3 or higher
• Composer
• Docker Desktop
  • Enable Docker Compose V2 in General settings
  • We recommend to set at least 8 GB RAM, 4 CPUs and 512 MB Swap in Docker -> Preferences… -> Resources -> ADVANCED
• Mutagen (install using Mutagen installation guide)

Steps¶

1. Create new project from Shopsys Platform sources¶

composer create-project shopsys/project-base --no-install --keep-vcs --ignore-platform-reqs
cd project-base

2. Installation¶

Now, you have two options:

Option 1¶

In the case you want to start demo of the application as fast as possible, you can simply execute the installation script and that is all:

./scripts/install.sh

After the script is finished with installing the application, you can skip all the other steps and see the last chapter of Application Setup Guide to get all the important information you might need right after the installation.

Option 2¶

If you want to know more about what is happening during installation, continue with the steps #2.1 - #2.5.

2.1 Enable second domain (optional)¶

There are two domains each for different language in default installation. First one is available via IP adress 127.0.O.1 and second one via 127.0.0.2. 127.0.0.2 is not alias of 127.0.0.1 on Mac by default. To create this alias in network interface run:

sudo ifconfig lo0 alias 127.0.0.2 up

2.2. Create docker-compose.yml and mutagen.yml¶

Create docker-compose.yml from template docker-compose-mac.yml.dist and mutagen.yml from template mutagen.yml.dist.

cp docker/conf/docker-compose-mac.yml.dist docker-compose.yml
cp docker/conf/mutagen.yml.dist mutagen.yml

2.3 Set the UID and GID to allow file access in mounted volumes¶

Because we want both the user in host machine (you) and the user running php-fpm in the container to access shared files, we need to make sure that they both have the same UID and GID. This can be achieved by build arguments www_data_uid and www_data_gid that should be set to the same UID and GID as your own user in your docker-compose.yml. You can find out your UID by running id -u and your GID by running id -g. Once you get these values, set these values into your docker-compose.yml into php-fpm container definition by replacing values in args section. Update also defaultOwner and defaultGroup in mutagen.yml to match your UID and GID.

2.4 Build and start containers using Mutagen¶

On macOS, you want to synchronize folders using Mutagen as it enables faster performance than current implementation in Docker Desktop.

Option A: Use the helper script (recommended)

./scripts/mutagen-up.sh

Option B: Manual steps

# 1. Start sidecar containers for Mutagen (with the 'mutagen' profile)
docker compose --profile mutagen up -d --build

# 2. Start Mutagen file synchronization
mutagen project start

# 3. Wait for initial sync to complete (check status with: mutagen sync list)
#    Look for "Watching for changes" status

# 4. Start all remaining containers
docker compose up -d

2.5 Set up the application¶

Application setup guide