Docker, Software Development, WordPress

WordPress on Ubuntu with Docker: Local Directory Mapping

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.

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.

Hard Symbolic Link in mapped Docker directory to local directory

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.

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.


Got comments or suggestions? We disabled the comments on this site to fight off spammers, but you can still contact us via our Facebook page!.

You Might Also Like