I was working on an existing WordPress theme that I have been using on this site. The plan was to start a Docker container for WordPress with a local directory for a WordPress theme project mapped to /var/www/html/wp-content/themes/my-theme within the container. However, WordPress cannot work with symbolic links pointing to a directory outside the Docker container but within the Ubuntu host.
This post uses PhpStorm (2023.3.2), Docker, and Lubuntu 22.04.1 (or Ubuntu).
Mapping Ubuntu Local Directory To Docker Directory
To provide more context, consider the following docker-compose file—lines 6 and 18 maps to two directories within the container.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | version: "2.3" services: wordpress-db: image: mysql:8.0 volumes: # Path is shorten for brevity - .../dips/bb/dip-wordpress/docker-volumes/turretadotcom/db:/var/lib/mysql # Omitted for brevity # ... turreta-wordpress: depends_on: - wordpress-db image: wordpress:latest # Omitted for brevity # ... volumes: # Path is shorten for brevity - ../dips/bb/dip-wordpress/docker-volumes/turretadotcom/wordpress:/var/www/html # Omitted for brevity # ... |
Then, suppose we have our WordPress theme codebase in /home/karl/Documents/__dev/projects/dip-wordpress/my-theme.
We must create a symbolic link in /home/karl/Documents/__dev/projects/dips/dip-wordpress/docker-volumes/turretadotcom/wordpress/wp-content/themes. Consider the following example.
We get the following output when we check the list of themes in WordPress. In this case, WordPress cannot detect the themes’ directories mapped as symbolic links to directories in the Ubuntu host.
Many of us may resort to changing permissions, the directory’s owner and group, or those of the symbolic link. However, those means will not resolve the Docker WordPress directory mapping issue. There is a simple explanation for this problem – from the Docker container instance, the directory the symbolic link points to does not exist in the container.
Access the Symbolic Link from within the Docker container.
We get the following error when we try to access the symbolic link from within the Docker container.
The directory the symbolic link points to does not exist within the Docker container, although the path exists within the Ubuntu host. From the Docker container’s perspective, the symbolic link is valid, but the path it points to does not exist.
One solution is to put the codebase within the /wp-content/themes directory. Using git, we could clone the repository in that directory. If the codebase is a sub-directory within a git repository, we may need to pull that sub-directory out and turn it into a git repository.
Alternatively, we could mount our local codebase directory as a volume within another volume. Consider the following modified docker-compose file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | version: "2.3" services: wordpress-db: image: mysql:8.0 # ... # Omitted for brevity # turreta-wordpress: depends_on: - wordpress-db image: wordpress:latest # ... # Omitted for brevity # ... volumes: # Paths are shorten for brevity - ../docker-volumes/turretadotcom/wordpress:/var/www/html - ../turreta-sparkle-theme/Themes/yeahthemes-sparkle:/var/www/html/wp-content/themes/yeahthemes-sparkle - ../turreta-sparkle-theme/Themes/sparkle-childtheme:/var/www/html/wp-content/themes/sparkle-childtheme networks: turreta_bridged: driver: bridge |
The path /var/www/html is where the WordPress is deployed within the Docker container. Also, the path has a mapping to a local host directory. Then, two theme directories are mapped to new directories within the WordPress /wp-content/themes path.
Finally, remember to configure the WordPress Support plugin in PhpStorm. The installation path should be the directory where the sub-directories wp-admin and wp-includes exist.
Also, add the directory to wp-includes.
The only setback for this solution is that we cannot perform git operations within the theme directory. We must do the operations within the original local Ubuntu path.
