Troubleshooting and HOWTOs

Avoid conflict with existing ports

1. Edit .env and add WP_PORT=80 and DB_PORT=3306 in the .env as default.
2. Edit docker-compose.yml and replace the host ports with ${WP_PORT} and ${DB_PORT} variables:

   Services:
     wordpress:
       ...
       ports:
         - ${IP}:${WP_PORT}:80
       ...
     db:
       ...
       ports:
         - ${IP}:${DB_PORT}:3306
       ...

3. End users may then change .env to avoid conflict with existing web server and MySQL/MariaDB ports on their host machine.

Enter into the running WordPress container to diagnose problems

1. Run docker compose up
2. Run docker ps to list running containers, and find the container name riskprofiler-cms_wordpress_1
3. Run docker exec -it riskprofiler-cms_wordpress_1 /bin/bash to enter the running WordPress container.

Warning: mysqli_real_connect(): (HY000/2002): No such file or directory in /var/www/html/site/wp-includes/wp-db.php on line 1653

Cause: wp-config.php provided upstream (e.g. HabitatSeven) is not configured for our Docker

Solution: Copy wp-config-docker.php to wp-app/site/wp-config.php, and maybe run fromdos or dos2unix to strip the trailing CR. No other change is required.

• wp-config-docker.php may be found in the top-level directory of https://github.com/docker-library/wordpress, or in /usr/src/wordpress/wp-config-docker.php inside the wordpress Docker image.
• wp-config-docker.php inherited the CRLF line-endings from wp-config-sample.php from WordPress.

Note: One can run docker exec -it riskprofiler-cms_wordpress_1 /bin/bash to examine /var/www/html/site/wp-includes/wp-db.php inside, though very few tools are available. Instead, with the volume mapping ./wp-app:/var/www/html defined in docker-compose.yml, we could just debug e.g. wp-app/site/wp-includes/wp-db.php from the host machine, and any code changes are reflected on the website immediately.

White screen (WSoD) Take #1

Symptom: The web page is rendered (actual HTML code returned), with <title> and all, but no actual content.

Cause (in our case): Missing theme files: wp-app/site/assets/themes/fw-parent is a git submodule which has not been fetched.

Solution: On OpenDRR/riskprofiler-cms, make sure both .gitmodules and wp-app/.gitmodules exist and point to the correct repos, and run git submodule update --init --recursive

What about built-in themes?

• twentytwentytwo theme requires WordPress 5.9+ and is incompatible with WordPress 5.8.x that RiskProfiler.ca is currently using
• twentytwentyone theme: cannot see the menu that leads to Scenarios, Risks etc.
• twentytwenty theme works! The top menu actually show!

White screen (WSoD) Take #2

Still not working! 😢

Cause: The hostname is set to riskprofiler.demo (port 80) in the database dump provided by HabitatSeven, but I did not set these properly.

Workaround:

1. Run sudo systemctl stop apache2 (on Linux), or stop your web server on port 80 using whatever means necessary.
2. Run docker compose down -v where the -v must be used so that changes to the .env to actually take effect. (Cached copy somewhere? Not sure...)
3. Edit .env and change WP_PORT=1380 to WP_PORT=80, and set IP=127.0.0.1 (in my case)
4. Edit /etc/hosts and make sure there is something like 127.0.0.1 localhost riskprofiler.demo
5. Run docker compose up
6. Import database by running import-wp-db.sh (which runs source .env and mysql < wp_habitatseven_riskprofiler.sql)
7. Visit http://riskprofiler.demo/

Better solution: Find a way to change the host name and port in WordPress (using WP-CLI, Phpmyadmin or mysql?)

Still not working! 😭

Let's try firing up WP-CLI for debugging...

How to get WP-CLI Docker to run?

See the wonderful answer by vstm at https://stackoverflow.com/a/51001043/3451096:

Edit docker-compose.yml and:

1. Add user: xfs so the user ID in the wordpress:cli image matches that of www-data in the wordpress image.
2. Add command: "sleep 1h" (or whatever command to keep the wpcli container up-and-running)

To test:

$ docker exec -it riskprofiler-cms_wpcli_1 /bin/bash
bash-5.1$ wp user list
+----+------------+--------------+--------------+--------------+---------------+
| ID | user_login | display_name | user_email   | user_registe | roles         |
|    |            |              |              | red          |               |
+----+------------+--------------+--------------+--------------+---------------+
| 1  | phil       | phil         | phil@example | 2021-10-20 1 | administrator |
|    |            |              | .com         | 3:23:53      |               |
+----+------------+--------------+--------------+--------------+---------------+

White screen (WSoD) Take #3

bash-5.1$ wp theme status
0 installed themes:

Legend: 
bash-5.1$ wp theme list
+------+--------+--------+---------+
| name | status | update | version |
+------+--------+--------+---------+
+------+--------+--------+---------+

Oh. Oh! I copied wp-config-docker.php to wp-config.php, but did not add HabitatSeven’s customization to it, namely:

define( 'WP_DEBUG_LOG', true );

$protocol = 'http';
if ( stripos ( $_SERVER['SERVER_PROTOCOL'], 'https' ) === 0 ) $protocol .= 's';

define ( 'WP_CONTENT_FOLDERNAME', 'assets' );
define ( 'WP_CONTENT_DIR', ABSPATH . WP_CONTENT_FOLDERNAME );
define ( 'WP_SITEURL', $protocol . '://' . $_SERVER['HTTP_HOST'] . '/site/' );
define ( 'WP_CONTENT_URL', WP_SITEURL . WP_CONTENT_FOLDERNAME );

define ( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );

After:

bash-5.1$ wp theme status
2 installed themes:
  A fw-child  1.0
  P fw-parent 1.0

Legend: A = Active, P = Parent
bash-5.1$ wp theme list
+-----------+--------+--------+---------+
| name      | status | update | version |
+-----------+--------+--------+---------+
| fw-child  | active | none   | 1.0     |
| fw-parent | parent | none   | 1.0     |
+-----------+--------+--------+---------+

and... Hurray! http://riskprofiler.demo/ is working on my local machine!

Why is wp-app/wp-config.php generated when I run docker compose up?

Examining https://github.com/docker-library/wordpress, we see:

1. In Dockerfile:

   COPY --chown=www-data:www-data wp-config-docker.php /usr/src/wordpress/

2. docker-entrypoint.sh tries to find wp-config-docker.php in wp-app/, then in /usr/src/wordpress/ ... (TODO: what is the difference between the two?), then convert 'put your unique phrase here' into actual random keys and salts.

Note that since HabitatSeven has moved the website into the site/ directory, WordPress actually tries to read from wp-app/site/wp-config.php rather than wp-app/wp-config.php, so, in OpenDRR/h7-riskprofiler, I have changed site/wp-config.php to a symlink pointing to ../wp-config.php to take advantage of the random keys/salts in the generated wp-app/wp-config.php file.

How to sanitize db-backup/wp_habitatseven_riskprofiler.sql?

For security and privacy reasons:

• In the wp_users table, change the '$P$Bxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' password hash to an empty string ('')
• Replace all real email addresses with [email protected]

How to log into phpMyAdmin?

• TL;DR: http://localhost:8080/, root, password

While phpMyAdmin shouldn’t be needed for our final workflow, it is definitely handy to have around for debugging.

• Username: root (superuser account)
• Password: Same as MYSQL_ROOT_PASSWORD, which is DB_ROOT_PASSWORD in .env because our docker-compose.yml says so.

See the "Credentials" and "Environment variables summary" sections on https://hub.docker.com/_/phpmyadmin for more information.

env_FILE mentioned in wp-config-docker.php?

Yes, putting something like wp-app/WORDPRESS_DB_HOST_FILE.txt with the content db inside, then adding #WORDPRESS_DB_HOST_FILE=WORDPRESS_DB_HOST_FILE.txt to .env, and setting environment in docker-docker.yml accordingly does work.

We probably won't need it, but in case we do:

• how do you manage secret values with docker-compose v3.1? - Stack Overflow

How to edit Simply Static settings with WP-CLI

It seems easiest to use wp option (see https://developer.wordpress.org/cli/commands/option/) instead of trying to mess with the mysql command:

$ wp option get simply-static
array (
  'destination_scheme' => '',
  'destination_host' => '.',
  'temp_files_dir' => '/Users/phil/Sites/habitatseven/riskprofiler/site/assets/plugins/simply-static/static-files/',
  'additional_urls' => '',
  'additional_files' => '',
  'urls_to_exclude' => 
  array (
    'http://riskprofiler.demo/site/wp-json' => 
    array (
      'url' => 'http://riskprofiler.demo/site/wp-json',
      'do_not_save' => '1',
      'do_not_follow' => '1',
    ),
    'http://riskprofiler.demo/site/wp-login.php' => 
    array (
      'url' => 'http://riskprofiler.demo/site/wp-login.php',
      'do_not_save' => '1',
      'do_not_follow' => '1',
    ),
  ),
  'delivery_method' => 'zip',
  'local_dir' => '',
  'relative_path' => '',
  'destination_url_type' => 'offline',
...

Desired settings:

  'temp_files_dir' => '/var/www/html/site/assets/plugins/simply-static/static-files/',
  ...
  'delivery_method' => 'local',
  'local_dir' => '/var/www/html_static/',
  'destination_url_type' => 'offline',

To update these nested values in the simply-static option, we use the wp option patch commands:

wp option patch update simply-static 'temp_files_dir' '/var/www/html/site/assets/plugins/simply-static/static-files/'
wp option patch update simply-static 'delivery_method' 'local'
wp option patch update simply-static 'local_dir' '/var/www/html_static/'
wp option patch update simply-static 'destination_url_type' 'offline'

(the quotation marks aren't needed, but they make it easier to read with my feeble eyes. 😄)

How to run Simply Static

1. Choose Save for offline use (Convert all URLs for your WordPress site so that you can browse the site locally on your own computer without hosting it on a web server.)
   • Rationale: https://beta.riskprofiler.ca/ is served from AWS S3, and the most straightforward and safest way for the URLs to work is to link them to index.html instead of to the directory (which S3 denies access by default).

(to be continued...)

Directories and IP address errors (Simply Static in Docker)

Unable to write to local_dir and temp_files_dir

TODO:

• Fix this heading
• Document the changes to docker-compose.yml, and how the directories need to be created on the host and chmod www-data:www-data before hand.

Checking if WordPress can make requests to itself from 172.27.0.4: Not a valid url

One-time manual workaround: Run docker exec -it riskprofiler-cms_wordpress_1 /bin/bash, and append the following line to /etc/hosts

172.27.0.4    riskprofiler.demo

Alternatively, add something like

    extra_hosts:
      - "localhost:172.18.0.1"
      - "riskprofiler.demo:172.18.0.1"

to the wordpress service section in docker-compose.yml.

It is difficult to automate though because the IP address is apparently assigned randomly by Docker’s internal DNS (just a random guess, I don’t know how all these work internally).

Fortunately, there is a better way that Docker Compose provides, and that is the use of network aliases like this:

    networks:
      default:
        aliases:
          - riskprofiler.demo

See:

• https://docs.docker.com/compose/compose-file/#networks-top-level-element
• https://docs.docker.com/compose/compose-file/#networks

About the default network, see the Docker Compose networks section below.

Using WP-CLI to run Simply Static with WP-Cron

Does it work?

wp cron event list

wp_archive_creation_job_cron

Docker Compose

command

• https://docs.docker.com/compose/compose-file/#command
• See also https://docs.docker.com/engine/reference/builder/#cmd

environment

• https://docs.docker.com/compose/compose-file/#environment

healthcheck

• https://docs.docker.com/compose/compose-file/#healthcheck
• https://docs.docker.com/engine/reference/builder/#healthcheck

Q: If a container ever becomes unhealthy, does it become healthy again?

Docker can’t be sure that taking action to fix the unhealthy container won’t make the situation worse, so it broadcasts that the container is unhealthy but leaves it running. The health check continues too, so if the failure is temporary and the next check passes, the container status flips to healthy again. (Chapter 8 "Supporting reliability with health checks and dependency checks", Learn Docker in a Month of Lunches by Elton Stoneman, https://livebook.manning.com/concept/docker/health-check)

Notes:

• Must set version to 3.9

networks

About the default network in this example:

    networks:
      default:
        aliases:
          - riskprofiler.demo

the fact that default network is built-in (and indeed the default) seems to be alluded to in the Docker Compose documentation, and is also seen in some answers on Stack Overflow, but nothing too concrete, or maybe I just haven't looked hard enough. But there are these assertions found in https://github.com/docker/compose/blob/v2/pkg/e2e/compose_test.go

		res = c.RunDockerCmd("network", "ls")
		res.Assert(t, icmd.Expected{Out: projectName + "_default"})
...
		res = c.RunDockerCmd("network", "inspect", projectName+"_default")
		res.Assert(t, icmd.Expected{Out: `"com.docker.compose.network": "default"`})

docker network ls

$ docker network ls
NETWORK ID     NAME                       DRIVER    SCOPE
d1aa8a1921e0   bridge                     bridge    local
53e7bd7c1602   docker_gwbridge            bridge    local
c4b8be809039   host                       host      local
de3b50f1864f   none                       null      local
ee6e4f3d17f9   riskprofiler-cms_default   bridge    local

docker network inspect riskprofiler-cms_default

[
    {
        "Name": "riskprofiler-cms_default",
        "Id": "ee6e4f3d17f9c8817e8ef558535290ee6a09e846c9b9ddb06ab281f9235ed2ba",
        "Created": "2022-04-25T13:41:16.907413305-06:00",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": [
                {
                    "Subnet": "172.18.0.0/16",
                    "Gateway": "172.18.0.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {
            "076d64aaf35f2011bb750345ce5f7fc0121966fa2a9b68ca0c231578c8fa6ce2": {
                "Name": "riskprofiler-cms_wpcli_1",
                "EndpointID": "2463b785022c6374e1374fbfe9ac3822a76e837a3f7c4025b7b536269e3bcdb3",
                "MacAddress": "02:42:ac:12:00:05",
                "IPv4Address": "172.18.0.5/16",
                "IPv6Address": ""
            },
            "83773a1c74348b97fa8f14d401afdcb0e62de1956faffa0ae08b90bc6a33d1ef": {
                "Name": "riskprofiler-cms_wordpress_1",
                "EndpointID": "1ea828ac0eddb9a068edf450af4cf494fcbf995684c9ec3a5d37005178d45afa",
                "MacAddress": "02:42:ac:12:00:04",
                "IPv4Address": "172.18.0.4/16",
                "IPv6Address": ""
            },
            "a7192b91cde456bd86e52d1aea754616536ff09ac6e3693a94134b8f223d2bf4": {
                "Name": "riskprofiler-cms_pma_1",
                "EndpointID": "17da91fb631c8b6ad9bfdd92a06966234c15a63ffb3371ee6c84db12d29817e3",
                "MacAddress": "02:42:ac:12:00:03",
                "IPv4Address": "172.18.0.3/16",
                "IPv6Address": ""
            },
            "c024e5570dcc06825a521b5e39f9ad975c34f577389c17db6cedc962d8718618": {
                "Name": "riskprofiler-cms_db_1",
                "EndpointID": "d90acef8a4efc64e7c77365405ee71af80226dc7f4a01d23579afdd12fca835c",
                "MacAddress": "02:42:ac:12:00:02",
                "IPv4Address": "172.18.0.2/16",
                "IPv6Address": ""
            }
        },
        "Options": {},
        "Labels": {
            "com.docker.compose.network": "default",
            "com.docker.compose.project": "riskprofiler-cms",
            "com.docker.compose.version": "2.0.0"
        }
    }
]

docker inspect riskprofiler-cms_wordpress_1

Excerpt:

        "NetworkSettings": {
            "Networks": {
                "riskprofiler-cms_default": {
                    "IPAMConfig": {},
                    "Links": [
                        "riskprofiler-cms_db_1:riskprofiler-cms_db_1",
                        "riskprofiler-cms_db_1:db_1"
                    ],
                    "Aliases": [
                        "riskprofiler-cms_wordpress_1",
                        "wordpress",
                        "riskprofiler.demo",
                        "83773a1c7434"
                    ],
                }
            }
        }