Improving the ReadMe (and other documentation)

[bordenc]

I'm struggling to follow the official readme, and I have to draw a lot of web searches to setup a basic container. Some specifics:

1. The readme omits that the image doesn't ship with its own database server. I haven't dug deep enough to see if there's been a debate on whether to package MariaDB, but the working scripts I've found online need this extra step. Nevertheless, it should be clear that the image doesn't work out-of-the-box;
2. The readme notes tweaks necessary to get SSL/TLS working, but I haven't been able to get them to work. I get errors when I try to enable TLS. Is there a known configuration with working TLS? Is it something that's beyond the readme's scope?
3. There appear to be typos in other areas:

• There are several environment variables strung together under How to use this image. I don't know if this is intentional.
• Adding additional libraries / extensions seems to have a sentence fragment: "If you need additional PHP extensions, you'll need to create your own image FROM this one."

(I haven't explored the other suggestions in the readme in much depth. They're somewhat over my head)

This is all to say that I'm willing to take a stab at PRing an edit to the readme, and other documentation, to ease the introduction to newcomers. I want some feedback and direction before I attempt to do so.

[tianon]

1. The readme omits that the image doesn't ship with its own database server. I haven't dug deep enough to see if there's been a debate on whether to package MariaDB, but the working scripts I've found online need this extra step. Nevertheless, it should be clear that the image doesn't work out-of-the-box;

Having a database inside the image would imply using a processor supervisor like supervisord, and deployments like that tend to be really unreliable and inflexible (it becomes much harder to separate the database from the backend). For example, what should the supervisor do if the backend dies but the database doesn't or vice versa? Should it kill the other? Clean shutdown? Restart the failing service?

By contrast, Docker itself (and k8s, c8d, etc etc) is a process supervisor at its core, so those concerns can rest appropriately with the operator instead - a failing service will exhibit naturally as a failing/stopped container.

2. The readme notes tweaks necessary to get SSL/TLS working, but I haven't been able to get them to work. I get errors when I try to enable TLS. Is there a known configuration with working TLS? Is it something that's beyond the readme's scope?

It's definitely something we've seen users have success with, but it is beyond the scope of our documentation (or support). I'd honestly recommend using a reverse proxy instead, at which point it'd be even better to do the work to use the FPM variants instead (which are a higher initial setup cost but with lower resource usage / better performance).

• There are several environment variables strung together under How to use this image. I don't know if this is intentional.

This is definitely intentional, especially as the names of these variables make their purpose pretty clear (and they match the variables of the same names in wp-config.php so should be familiar to WordPress users in general), so we didn't clutter the image description with extra exposition.

• Adding additional libraries / extensions seems to have a sentence fragment: "If you need additional PHP extensions, you'll need to create your own image FROM this one."

I'm not sure which part of this sentence is missing? This reads correctly to me as-is (FROM here is referring to the FROM instruction in a Dockerfile).

[bordenc]

@tianon The sense I get, therefore, is that the maintainers are satisfied with the documentation as is and any revisions I attempt will be rejected?

Although I have some experience with WordPress, and I have a general understanding of containers (although I'm struggling to understand what practical use they have since they seem to be so limited in their functionality), I have yet to set up a usable WordPress development environment, despite leaning heavily on outside sources. The WordPress container's readme gives me no clarity.

My feedback, therefore, is that either I don't meet the prerequisites to understand the readme (in which I'd be grateful for direction on what I should understand before attempting to use it), or the readme is missing information.

[polarathene]

I have a general understanding of containers (although I'm struggling to understand what practical use they have since they seem to be so limited in their functionality),

Containers provide improved portability and confidence in deployments since the environment is more deterministic. The images are generally intended to be small immutable components that you can piece together for each project (such as WordPress and a Database as separate images), which provides a little bit of friction but more flexibility (easier to swap out images for example) and often easier to maintain/update on your end once setup vs software versions being held back if depending upon a single image author. Runtime state and data is either ephemeral or can be persisted via volumes.

I maintain a mail server container that bundles multiple programs to provide that logical service, which like mentioned above relies on software such as supervisord. Such an image is uncommon, but it caters to an audience where deploying a logical service as a whole makes more sense for them and is far simpler than the alternative projects with massive compose.yaml or other complexities, but it's not without it's disadvantages either. I'd generally encourage the separation when it makes sense to do so.

FWIW, you can often still take the approach of building a custom image with everything you need with your preferred base distro (Ubuntu/Debian/Fedora/etc). So any online guides could be followed, but this requires you to know what you're doing considerably more than only being an image consumer (or extending one) which would allow you to invest your time elsewhere instead, so most prefer to delegate image maintenance / knowledge to a third-party (in this case official images are quite trustworthy) but you may have some initial friction adapting to that or should you require modifications that are more niche.

---

As for the TLS concern, absolutely go for a reverse proxy like Caddy. If you've not used one before, again there is a bit of a learning curve but Caddy is one of the simplest to get set up and has a very friendly community forum to get assistance and guides (they even have one with wordpress IIRC).

I get errors when I try to enable TLS.

Probably not the cause, but worth being aware of the following:

• Bind mount only directories from the host, otherwise you lose updates of changes from the host to the container if the inode changes, while the container likewise will not be able to update the file on it's end if it needs to when the inode would change.
• Containers have an internal filesystem, this will persist across container restarts or when the container is stopped/started, but be discarded when the container is (such as replacing it with a new container instance from the image). This can sometimes confuse users with startup scripts for a container which run when starting the container again, but the container has changes to it's files compared to the image which could lead to bugs if not careful.
• Anonymous volumes from VOLUME instruction in an image can also introduce unexpected failures, notably when paired with Docker Compose and making changes to a service where your expectation was a clean-slate of the container instance like you'd get without compose involved.

The readme notes tweaks necessary to get SSL/TLS working, but I haven't been able to get them to work.

The only guidance at the readme you mentioned is related to reverse proxy usage and the WordPress docs that links to for more info.

I don't use this image myself, just landed on this issue and thought I might be able to provide some helpful insights 😅

According to this, should you adopt Caddy you don't need to worry about that header config as Caddy already does the right thing out of the box for you.

Here's some threads about configuring this WP image with Caddy and Docker Compose (slightly dated but might be helpful for you):

• https://caddy.community/t/running-caddy-with-wordpress-php-fpm-with-docker-compose/21526
• https://caddy.community/t/wordpress-docker/22254

If you run into any trouble with Caddy, that's the forum you'll want to post at for assistance :)

[bordenc]

@polarathene I appreciate your comments, although I'm afraid I struggled to understand them. I think I unrealistically expected containers to provide turnkey functionality analogous to a flatpak. From my reading, feedback and experimentation over the past few weeks, it seems that containers cannot (or aren't supposed to):

• mount host folders into the guest to sync data (I've filed a separate issue about ambiguities in the documentation for the VOLUME instruction)
• run more than one process at a time
• run daemons (and certainly not during setup to do things like configure a database)

As you mention, you've coerced containers to accomplish something useful with lots of expertise and skill. Newcomers like me are relegated to running prepackaged demos. It kinda reminds me of using macOS: it looks really great and snappy until you try to get actual work done.

To this end, I'm trying to get my WordPress development environment by building a full virtual machine, which feels like using a wood chipper to make a milkshake. But at least I understand and can control a virtual machine guest.

That returns me to my original feedback about the WordPress readme: I think it should state that it's not a turnkey environment, but designed for experienced container developers.

[polarathene]

I think I unrealistically expected containers to provide turnkey functionality analogous to a flatpak. From my reading, feedback and experimentation over the past few weeks, it seems that containers cannot (or aren't supposed to)

They provide a simplified and portable way to distribute software, as opposed to a system package manager or one more broad like snap/flatpak.

• However apps you install on your system tend to come with a set of defaults and the user configures that directly afterward.
• An image isn't that different, but some will attempt to provide conveniences that may have some opinionated config or additional features. Once you're familiar with that, you have common base you can continue to work with.

I maintain Docker Mail Server (DMS), it's often praised for simplifying deployment of such a service and it truly is simple to get started with it with little knowledge of the underlying software that runs. To achieve that certain assumptions are made by default, while users can either use the additional conveniences we provide, or when we don't it has been documented how to manually override for power users that want to directly configure software.

Once a user has a setup they like, all they need is their compose.yaml and they can deploy that to a new system easily. Volumes can likewise be backed up and copied over if they're migrating. Similar to a VM image, except the user only needs to be concerned with their volume data and compose.yaml, none of the image contents. So it is very easy to reason about upgrades to the service, every user may have a different deployment requirements and use-cases but they all share the same volume mounts and will have very similar compose.yaml.

---

• mount host folders into the guest to sync data (I've filed a separate issue about ambiguities in the documentation for the VOLUME instruction)

An image should not dictate such. VOLUME only communicates a path in the container that should persist the data, so Docker will manage that for the user without them having to think about it. Anonymous volumes aren't something I'd choose for data you care about however.

Instead of implicit configuration, prefer that users explicitly state where they will store their data. You don't have to type that out each time you run a container, using compose.yaml it'll be encoded once and anyone who copies that and is happy with the default location there can also avoid configuring it, otherwise change it to what suits them.

Since it's not installed (and managed) by a package manager or similar, it does not assume to know where data should be persisted to. There are various registries for sourcing images, and multiple images that provide the same software/functionality (official or third-party), it is flexible this way and avoids conflicts. The broader range of how containers would be used kind of makes it difficult to implicitly convey this information, unless you're happy with named/anonymous volumes.

run more than one process at a time

You absolutely can. As mentioned I maintain an image that does just that. It's just generally discouraged, you don't have the benefits such as systemd (in Docker at least it is problematic IIRC, Podman can do it).

You can as advised, use each container as a logical service and orchestrate via Docker Compose, which depending on how you approach it can work well or be a painpoint.

If you want to manage multiple processes in an image, it would be like you would on a host system (or VM), which normally you have handled for you by the distro / packaging maintainers. When you build your own image effectively from scratch without all those conveniences, you'd need to leverage something like supervisord or pebble. It's not particularly difficult to add these, but it will add to your learning curve if you're not familiar with them, along with any troubleshooting you may encounter if you're not on the happy path.

run daemons (and certainly not during setup to do things like configure a database)

Again possible, the image I maintain does a fair bit to prepare the image, and then has setup on first run, followed by delegating to supervisord to manage the daemonized services in the background.

Most images don't do this as it's a hassle. You may be interested at looking at LinuxServer.io images which do try to cater to supporting a variety of images with s6 as the init system. Here is their docs for hosting a WordPress site using Docker Compose with two containers.

At a glance they're not offering a direct solution there for you, but you can probably derive one from that once up and running. Otherwise go with the official image here, it depends on what looks the most approachable for you.

---

As mentioned, with DMS the audience is users that want everything in a single container image. That has a tradeoff, and as a user you need to find and choose what works best for you. That's not necessarily the official or most popular image of a software you're interested in, but those can be far easier than doing it from scratch. Just get everything working first and then bring in your own changes after that point.

As you mention, you've coerced containers to accomplish something useful with lots of expertise and skill.
Newcomers like me are relegated to running prepackaged demos

I started with just using official images, no custom Dockerfile. I used compose.yaml early on and followed the docs/guide for an image along with going over the official Docker Compose docs or looking at what others were doing for reference.

For the most part you really don't need to know much.

services:
  some-name:
    image: image-name:tag
    volumes:
      - ./relative-path/on/host:/container/path
    ports:
      - 80:80

# Start the container
docker compose up -d

# Access the container and run any extra commands if needed:
docker compose exec some-name bash

docker compose down

That would get you fairly far with most images. Provided they document the port(s) and volume path(s) to mount in the container.

Other than that there's usually some configs (files or ENV), possibly some first-time setup if you've not got existing data via a volume.

After that when deploying for public access with TLS you'd want to bring in a reverse proxy container for all the traffic to flow through, and that container will route the traffic to the containers on the same shared docker bridge network.

It's quite a bit to digest when you're starting out but gets easier and is worth it IMO if you have quite a lot to deploy (either with various third-party images, or even many similar projects that could utilize the same image base).

I managed a server like that for a few years that served a few thousand users each month, no custom images. It was simple enough to just update the official image as needed and update the volume mounted git folder, and run a few commands manually (if necessary) or just restart the container. Using containers was still quite beneficial that way in a VPS deployment vs without containerization on the host.

If this still feels too technical for you and you really don't have much actual services you need to run, something that can do PaaS might be more up your alley. Think Heroku or the self-host equivalent Dokku. I haven't been keeping up in that space, so I'm not familiar with what's the goto for that now when self-hosting, but it sounds like you're seeking that instead. CapRover has WordPress supported as a one click app.

That returns me to my original feedback about the WordPress readme: I think it should state that it's not a turnkey environment, but designed for experienced container developers.

At a glance it doesn't look like there's anything that specific about container experience from the DockerHub page required to deploy this image. You might as well raise that concern with every image in that case.

I haven't installed WordPress myself, so I don't know how it compares to you doing so manually but it shouldn't be all that more complicated tbh 😅

For example in the previous community forum link I provided:

services:

  wordpress:
    image: wordpress:php8.4
    restart: unless-stopped
    container_name: wordpress
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: wordpress-db
      WORDPRESS_DB_USER: exampleuser
      WORDPRESS_DB_PASSWORD: examplepass
      WORDPRESS_DB_NAME: exampledb
    volumes:
      - ./wordpress:/var/www/html
      -./custom.ini
  db:
    image: mariadb:11.2.2
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: exampledb
      MYSQL_USER: exampleuser
      MYSQL_PASSWORD: examplepass
      MYSQL_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - ./db:/var/lib/mysql

networks:
  default:
    name: caddy_network
    external: true

• There's two containers setup, one for WP and another for your database of choice.
• The container port 80 is published to host network at 8080. This isn't necessary given they're using Caddy, a reverse proxy makes port publishing for proxied containers redundant.
• Then there's the environment variables to configure the credentials to the database. They're using the implicit wordpress-db here for the host (assumes the folder or compose project name is wordpress), they could have been explicit instead.
• Data is mounted with some custom config.
• The separate db service is effectively the same so self-explanatory there.
• Finally there's a network customization that's changing the default network to an externally created one (to the reverse proxy, Caddy).
  • This might be a little advanced for someone new, but the rest prior should be quite common to see and learn about.
  • Seeing a config and looking up the Compose docs to understand what is not familiar is much easier than having the existing expertise to make changes yourself. Many people learn from existing references when starting out this way regardless of the tool.

The link then shows a separate config they have for Caddy, since they're using that to support multiple compose projects. Reverse proxies are a bit more to your learning curve, but again the basics are quite easy to get up to speed with and get going and that's enough, just like git or whatever expertise you presently have you rarely need to be an expert.

The above is very similar to what the official DockerHub docs for the image show for compose.yaml, they just skip the reverse proxy part.

Anyway, your expectations with Docker images and deploying them differs in a way that I doubt is specific to this image. There's nothing wrong with that, but I would suggest looking at something else if the above still seems too overwhelming to grok.

If you still want to pick up expertise with containers, keep it simple and start from something even simpler. A great way to learn is to break complexity down until it's easier to understand, then work your way up til it finally clicks, then this sort of generic config process will be a walk in the park 👍

[bordenc]

@polarathene once again, I'm very grateful for your thoughtful and thorough response.

At a glance it doesn't look like there's anything that specific about container experience from the DockerHub page required to deploy this image. You might as well raise that concern with every image in that case.

I think reasonable people can disagree on this, which is why I solicited feedback before trying to write a PR. Quoting the Hub page:

How to use this image

$ docker run --name some-wordpress --network some-network -d wordpress

The following environment variables are also honored for configuring your WordPress instance (by a custom wp-config.php implementation⁠):
...

I understand an "application" to be the interface point between the user and the software iceberg. If the application is "WordPress," the database implementation is largely irrelevant to me. Indeed, as I think you imply, many hosts sell their WordPress hosting products along the lines of "Give us your admin account username and password, and we'll handle all the fiddly bits behind the scenes."

Therefore, I expected (as in predicted, not demanded) that running docker run -d wordpress would handle the database backend for me when, as you point out, it does not, and give me a running WordPress server in which I could connect and start building. Perhaps someone experienced like you intuitively knows that an apache daemon and mariadb daemon shouldn't roll into the same contanier, but someone like me doesn't.

To me, it's analogous to buying a car and then being told I need to source and install my own engine. I would have assumed that an engine came with the car, but you could (I think quite reasonably) argue that it's not how Bespoke Hotrods Inc. packages their cars.

For further clarity, my feedback isn't a demand that this Docker project overhaul its processes and documentation to suit me. I'm commenting on where I've gotten quite stuck in hopes that whatever changes they do make (if they make them) prevent more people like me from raising issues. A little work now to avoid a lot of repetitive work later.

My general philosophy to software support is that if the software is working as designed but not as the user expects, then the bug is in the documentation.

[polarathene]

Perhaps someone experienced like you intuitively knows that an apache daemon and mariadb daemon shouldn't roll into the same contanier, but someone like me doesn't.

You can do this, it's just generally not encouraged as it rarely makes sense to do that. Someone may have published an image that does bundle the DB for you (but then you must trust their image is not malicious), or you learn enough to build your own image (kinda defeats the intent of convenience if that's quite a bit of unfamiliar territory to achieve it).

I would say that your perspective is focused on a single image, while the expectation would still be satisfied with multiple images, but run with Docker Compose. So instead of a docker run command, you move the config into a compose.yaml file like the DockerHub page documents, and then run docker compose up.

This way you still get the experience of a single command that brings up both WordPress and a Database with the common configuration handled.

In projects it's often about which audience you're going to cater towards as there are different often conflicting expectations. You may not care about the choice of database, or being able to update it at a separate pace, while others do. In some projects a database isn't necessary for trying the software out and adds weight or added complexity to the image, but providing that flexibility comes at an extra cost (mostly alleviated with the compose.yaml example however in this case).

I'm commenting on where I've gotten quite stuck in hopes that whatever changes they do make (if they make them) prevent more people like me from raising issues. A little work now to avoid a lot of repetitive work later.

I understand, but those concerns are largely due to inexperience and possibly XY problem in that it's like you're going to a McDonald's and asking for a Whopper burger. Both places have their version of a burger and they're more than happy to give you the ability to customize from the default to your preferences where possible, but there are certain aspects that are opinionated preventing you from getting that competing burger joints product at the competitor 😅

Especially if the complaint was that one burger joint was serving up burgers when you perhaps expected pizza, each seems to have the common ingredients available, and staff to prepare it, or you end up at place that gives you the ingredients to make your meal instead.

Check that CapRover link I provided, if you're comfortable setting that software up, then you might prefer their approach?

My general philosophy to software support is that if the software is working as designed but not as the user expects, then the bug is in the documentation.

That is valid, but again users sometimes have conflicting expectations.

Your expectation largely conflicts with what most images will cater towards and what the majority of Docker users expect. However Docker Compose does steer you towards the direction you were expecting, provided the software has documented an example of that for you and you grok the basics like I walked you through in my previous post.

[bordenc]

Decades ago (and I'm quoting from memory) comedian Hunter Cressall (one of many spellings I've found) described using Macs: "I don't feel so much that I'm using a Mac as I'm there sharing the Mac experience. If I can get something useful done while the Mac is willing, so much the better."

That's my impression of containers. Although you've stated many times that it's technically possible to get a container to adapt to my workflow, I should really work on adapting my workflow to the container. It's a pretty audacious marketing pitch that only a few brands (like Apple, and apparently Docker) get away with.

It also reminds me of Blender pre 2.5. I was working through a Blender tutorial that warned from the onset that the interface would feel awkward and cumbersome. In time, the tutorial promised, I would realise how incredibly efficient and productive Blender's design was. Yet the Blender community was baffled at how tepid adoption was in spite of the "superior" design. To try to demonstrate Blender's capabilities, they made short movies. Evidently, along the way, they must have discovered that their theoretically perfect UI was actually a practical nightmare, since they overhauled it from 2.5 onwards. After that overhaul, real animators started looking at it.

I think we can agree to disagree that this package promises something it doesn't deliver. I don't think it's fair to expect someone with a reasonable (but not thorough) understanding of containers to know that this isn't a turnkey image. You may be right that I'm the only person who has or ever will complain about not being able to use this package. But I don't think I'm that special.

If I understand correctly, you haven't worked with this particular image in any depth. I'd be interested in your thoughts once you have. That's an invitation, not an order :-)

[polarathene]

It's a pretty audacious marketing pitch that only a few brands (like Apple, and apparently Docker) get away with.

I've tried to use macs several times in my life and each time had an unpleasant experience. It's tailored to a specific audience that is far less likely to encounter the usability issues I had with it.

Windows was better, but not without it's own quirks that caused much frustration. Then there is Linux and while not perfect either, I actually felt a sense of freedom to (within reason) address many of the issues I did encounter, and a community and knowledgebase that was far more accessible and useful to me than those I would find within Windows and macOS.

For the majority of people I know outside of work (or even within), Linux was not ideal for them, even for those that did try give it a go, without me readily available to provide guidance and troubleshoot any initial friction with adopting something unfamiliar most would go back to their comfort zone if whatever motivation to leave it wasn't strong enough to warrant the effort of learning a new ecosystem.

Docker, like many things in tech can cater to a wide audience, but how your journey pans out with discovering and engaging with it can end poorly or positively. It's all about the approach, and when you're left to figure that out yourself with an abundance of resources catering to vastly different audiences... it can be very challenging.

The first step though is to consider the XY problem and quickly verify if pursuing the goal is actually aligned with what you need. In the case of Docker, it's scope is rather broad, it's not always clear how to begin or what you should know first up since that's going to vary person to person.

The next step is to as quickly as possible, go through the basics, ignore your more specific goal and just get familiar with the concept you're pursuing (such as easy, predictable, immutable deployments that can be redeployed/modified across projects instead of too much manual work, your goal is to be DRY).

A common problem with Docker is new users will learn about images being built with a Dockerfile and come across resources that detail how to do this, when really they'd be fine most times keeping it simpler and deploying an existing image as-is. After which, the next thing to learn is Docker Compose.

Once you understand these basics, you'd know if this is really the correct tooling for your requirements. How long it takes to reach that point and sift through content that isn't relevant (which is difficult to detect when the bulk of it is all new / unknown) is going to vary, especially without engaging in a community for guidance.

---

Evidently, along the way, they must have discovered that their theoretically perfect UI was actually a practical nightmare, since they overhauled it from 2.5 onwards. After that overhaul, real animators started looking at it.

I remember it, but not so much any reasoning /details. I was professionally trained for film/games as a 3D artist with Maya, I got more into the role of a technical artist, and then fully switched over to programming.

That prior Blender UI was definitely a barrier to adoption for me, but like with most interfaces we get accustomed to I can't quite say this wasn't due to biases already developed for how things felt like they should be. You'd see similar complaints form users that started with Blender / GIMP and got experienced with that to when they tried proprietary software interfaces and couldn't see the appeal.

There's also different styles of learning and how we think/reason when it comes to problem solving. Before switching over to become a developer I was very much into UI and UX design too, so I am aware of that concern, but it's not the only barrier for users. Even programming languages without the visual aspect have these concerns, which affects preference. The psychology is applied throughout many areas of life, but trying to appease a wider demographic is not easy to achieve, you often get fragmentation or other drawbacks.

With Linux we have the various distros where communities specialize on a particular demographic. With Docker (or container ecosystem in general) you'll likewise find this fragmentation with the more established options being Docker Compose and Kubernetes, both tailored to rather different expectations.

An image is a building block towards those ecosystems that build around it.

---

I think we can agree to disagree that this package promises something it doesn't deliver.
I don't think it's fair to expect someone with a reasonable (but not thorough) understanding of containers to know that this isn't a turnkey image.

What exactly are your expectations? You've wanted an easy to deploy instance of WordPress that you can self-host instead of going through a paid proprietary provider?

Your main complaint was the lack of a bundled database, and then TLS.

1. Docker Compose encodes everything into a single compose.yaml file. There's very little to grok about it, you copy/paste and make some changes to the credentials. You now have a single simple command to start the two containers and they're configured to interact already, as per your expectation.
2. TLS is rather vague. There are many different ways to sort that out and many different conflicting opinions on how. An official image trying to best accommodate such requirements is not able to make these assumptions on your behalf.

I am not familiar with your experience in deploying WP + DB elsewhere, or how it compares it difficulty/effort from that to what you have with the compose.yaml. I can say from my experience that many software projects have been vastly simpler to deploy with a container than without one, and I standby that even from when I was inexperienced with Docker.

Reverse proxies are very common and standard today, and as I've said already there really isn't that much to grok to get the "happy path". Learn once, then benefit from then on with reuse. I directed you to Caddy, something I wish was available when I started out given how much nicer it is vs say nginx and apache.

The happy path with Caddy is deploying to a server with public IP that can provision certificates for TLS via LetsEncrypt, this is the default with Caddy. I've personally needed to use a private CA instead of LetsEncrypt, or external certs I've self-signed and provisioned locally for testing. Caddy + LetsEncrypt will automatically renew your certs for you before their 90 day expiry window ends, whereas if you do this manually instead to avoid a separate container, you have extra work maintaining it (unless you're automating via some other means on the host or another container).

It seems your biggest issue is the paradox of choice and you'd prefer someone else to make more opinionated decisions on your behalf so that you do not need to. Suggestions and the example compose.yaml at DockerHub (or that I linked from Caddy forums) do this to some extent, but if you want to disregard the transparent configuration benefit, then do as you've been advised and look at a PaaS solution like CapRover with it's one-click-app deployment web UI (which includes WP).

You may be right that I'm the only person who has or ever will complain about not being able to use this package. But I don't think I'm that special.

I'm simply stating your complaint wouldn't be specific to this image. It looks fairly standard in the Docker ecosystem.

It's alright if Docker is not for you. I've tried to provide you with advice on how to have a better experience, but not received any feedback on such. From that I can only infer that you'll be happier elsewhere, should you find what you're looking for. If you instead actually learn the basics I've tried to communicate to you, then you should find Docker is quite simple for deploying a wide range of software.

If you're only interested in WordPress deployments, there's probably something else out there that's specialized on that. I know there's other options out there that have a lower barrier to entry, they just don't appeal to me for the same reasons I prefer Linux over Windows / macOS.

[polarathene]

If I understand correctly, you haven't worked with this particular image in any depth. I'd be interested in your thoughts once you have. That's an invitation, not an order :-)

As stated, I've had plenty of experience using Docker with a variety of software projects. The DockerHub README for this image looks perfectly adequate to me to what I'm used to seeing.

I'm not sure what your expectations are from me trying the image. Beyond getting the container to run, what constitutes as confirmation of ease of deployment? That I get a WP admin page after logging via the browser with HTTPS?

---

Here is all you need to do to get going 🤷‍♂️ I've added some additional commentary should it be helpful.

With Docker + Docker Compose installed (as per official docs), create the following compose.yaml:

services:
  # Caddy as a reverse proxy, all incoming web traffic is routed through this container.
  # Caddy will handle managing TLS for you to secure web traffic. No other container needs
  # to worry about configuring for TLS.
  reverse-proxy:
    image: caddy:2.10
    # Publish the web ports for HTTP + HTTPS:
    ports:
      - 80:80
      - 443:443
    # This example is using a Docker Compose feature `configs`
    # to embed the Caddy config file, normally this would be
    # an external file provided via bind mount with `volumes`,
    # but you can continue to embed it in your `compose.yaml` if  you prefer.
    configs:
      - source: caddyfile
        target: /etc/caddy/Caddyfile
    # NOTE: I've not included standard volumes to persist data here,
    # you must do this for proper production deployment to persist your certs.

  # These two remaining services are copy/paste from DockerHub,
  # except I removed the wordpress port mapping since Caddy handles routing traffic.
  wordpress:
    image: wordpress
    restart: always
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: exampleuser
      WORDPRESS_DB_PASSWORD: examplepass
      WORDPRESS_DB_NAME: exampledb
    volumes:
      - wordpress:/var/www/html

  db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_DATABASE: exampledb
      MYSQL_USER: exampleuser
      MYSQL_PASSWORD: examplepass
      MYSQL_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - db:/var/lib/mysql

# Persisting data for services via named volumes:
volumes:
  wordpress:
  db:

configs:
  caddyfile:
    content: |
      # Respond to https://example.com
      example.com {
        # This is just for local testing, remove this `tls internal` line
        # in production to provision certs for `example.com` via LetsEncrypt:
        tls internal

        # Route the connection to the wordpress containers port 80:
        # - `wordpress` is a hostname via the service name above
        #   that Docker implicitly adds to it's internal DNS config.
        # - This requires that both Caddy and the wordpress container
        #   have a common network to reach each other.
        #   By default Docker Compose has a separate network per `compose.yaml`
        #   If you have multiple `compose.yaml` files then you need to configure
        #   external networks like the Caddy community reference links demonstrated.
        reverse_proxy wordpress:80
      }

Now start the containers. Technically you only need to know docker compose up and you're good to go:

# `-d` will start the containers in the background instead of tailing the logs.
# Use `docker compose logs -f` command to get the same output should you need it.
# `--force-recreate` is optional and ensures that containers are created new,
# discarding any internal state that isn't persisted via volumes.
# Be mindful of anonymous volumes from the images `Dockerfile`, as resetting those
# requires a different option.
docker compose up -d --force-recreate

# Bring down the containers if needed:
docker compose down

That's all there is to it.

All I've done is added in a Caddy container into the compose.yaml with very minor modifications, then added it's own basic config file to route port 80/443 to port 80 of the wordpress container. Caddy is optional but it does simplify many things like TLS and port mapping for example.

Bare in mind once you start that if you access it from a public domain instead of say localhost you'll have no protection in place for initial setup. Look at the Caddy docs, add in something like basic_auth directive temporarily if that is a concern for you (it will protect all traffic to the wordpress container via a username/password credential).

On a public deployment, remove tls internal for trusted TLS certs (you can first test with tls internal on a public VPS if you prefer), and make sure you add the volumes to persist the certs (see the Caddy DockerHub).

The current wordpress image is Debian 13. If you decide to deploy this to production be sure to pin the image version via tag.

---

I had no problems at all getting this up and running. The instructions were very basic and copy/paste as you can see.

I'm not wanting to go further and hand-hold as free IT support for any further configuration of this specific software.

If you have familiarity with deploying wordpress in VMs, it's not all that different, just docker compose exec wordpress bash and now you have a shell into that container. You'll be root and can install whatever packages followed by config updates that you need to get the install how you like it.

After you're happy with that, should you want to avoid repeating those additional changes, extract any files out to persist via volumes (either copy/paste or docker cp command) or COPY in Dockerfile, and any additional packages needed via RUN on Dockerfile (an entrypoint script could also technically do this, but it's better to handle packages via an image build).

Just to clarify, you do not need to publish your Dockerfile build to a registry to use it. You can keep that all locally and your compose.yaml can refer to an external Dockerfile or it can inline one into the compose.yaml itself (see the Docker Compose build docs) if that is more convenient.

---

If what I've detailed above still feels overwhelming and too much effort (copy/paste 1 file, run 1 command, add your own changes that suit your specific needs), then Docker is not for you.

[bordenc]

@polarathene I'm much obliged. I just wish the readme had something to the effect of what you provided so you don't have to provide free IT support and hand-holding. I know that your time is valuable and I wouldn't have resorted to opening an issue if I hadn't exhausted my wits trying to figure it out myself over weeks.

That I get a WP admin page after logging via the browser with HTTPS?

Well, HTTPS isn't necessary, but I don't think having a WordPress site that I can connect to is entirely unreasonable under a heading of "How to use this image".

Anyway, it seems that this won't be fixed and, since I have a working virtual machine that runs WordPress, I'll use that instead. I'm very grateful for all the time you took in responding, and I'll revisit your advice if I attempt containers again.

[polarathene]

I know that your time is valuable and I wouldn't have resorted to opening an issue if I hadn't exhausted my wits trying to figure it out myself over weeks.

It's ok, I am quite familiar with the struggles when learning something new, reaching out and communicating is encouraged.

I often invest far too much time solo before I reach out for help, only because when I started out communities back then were much less welcoming unless you could demonstrate your attempt alone. These days things have changed, plenty of communities have forums or real-time chat like Discord to engage on, even AI tools are somewhat helpful at times.

I quite enjoy helping out peers with sharing my insights, but I also need to get better at knowing where to draw the line, otherwise I lose productivity on pushing forward on tasks I need to tackle 😅

---

I just wish the readme had something to the effect of what you provided so you don't have to

Could you be more specific please? The DockerHub does provide the bulk of the compose.yaml, only TLS would need to be addressed.

I assume that was left up to the reader to resolve, since it's not as essential as the database and will vary quite a bit by preference for how to configure it. The docs could include something with Caddy like I did, but then the maintainers may also be burdened with support requests for that when it's not actually something relevant to the core project itself to maintain.

It would be mostly redundant for every image with a webservice to document that same information, which only adds more noise to the individual image docs. So I can understand why it'd be preferred not to do that. A docker image I maintain does document it, since TLS support is a bit more non-standard with mail server and reverse proxies, but it's often resulted in support requests still because we don't cover enough information (despite how extensive and organized that one topic of configuration is covered already).

As such, images will tend to expect the user to know how to handle this as a prerequisite. Once you know the basics for that you don't really need to think about it much again. When starting out, without the right resources, it may be more difficult due to choices/opinions and a variety of ways to configure this functionality.

What you need was not for this particular images documentation to guide you, but a better introductory guide into using Docker in general. Initially they'd skip a reverse proxy, but it makes much more sense once TLS is involved.

---

Well, HTTPS isn't necessary, but I don't think having a WordPress site that I can connect to is entirely unreasonable under a heading of "How to use this image".

If I connect over HTTP, this logic forces redirection to HTTPS from WordPress:

wordpress/wp-config-docker.php

Lines 120 to 124 in bdaac32

	// If we're behind a proxy server and using HTTPS, we need to alert WordPress of that fact
	// see also https://wordpress.org/support/article/administration-over-ssl/#using-a-reverse-proxy
	if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && strpos($_SERVER['HTTP_X_FORWARDED_PROTO'], 'https') !== false) {
	$_SERVER['HTTPS'] = 'on';
	}

If I override the header sent from Caddy for HTTP to instead set that header as https, then it'll redirect to HTTP for login, but with a redirection URI to HTTPS after login... so the image is enforcing HTTPS for admin. It does work fine for visiting the main site after setup though.

So yeah it probably could point out that caveat better 😓

Self-signed certificates though will work fine for satisfying the HTTPS requirement (you'll get a warning that it's potentially insecure when your connecting device doesn't have the self-signed CA in it's system trust store).

---

Anyway, it seems that this won't be fixed and, since I have a working virtual machine that runs WordPress, I'll use that instead.

All good, stick with what's comfortable 👍 If you adopt this image and you're more familiar with configuring WordPress, then be sure to get familiar with the changes the image has added such as referenced above 😅