Modify config example, and improve APPLY_EXTRA_FILES example

[Firefly7-7]

Enhancement Type

Improve an existing feature

Describe the enhancement

Looking at the example configs, it doesn't look like there's an example of how to patch an existing config file. The closest is the extra files example.

From the documentation, it is not clear that the file needs to be added to the data directory through APPLY_EXTRA_FILES. It is somewhat mentioned in the documentation for APPLY_EXTRA_FILES, but that seems like the wrong place to put it.

In the example for APPLY_EXTRA_FILES it seems like it also wants you to share the a volume, which doesn't make much sense. Seems like this might be able to be avoided after #3748, though. Also, an example for copying a single file instead of a directory would be nice, as this is simpler for a variety of usecases, including the one shown.

[itzg]

The patching feature always has to process an existing file. Yes, APPLY_EXTRA_FILES is one of several ways to get a file in place in the /data directory just before patching happens.

[Firefly7-7]

Yes, it obviously has to process an existing file, however it is not clear from the documentation (at least to a newbie docker user) that the file already has to exist inside of the container. The lack of an example makes this even more difficult to discover. The fact that APPLY_EXTRA_FILES is able to fail if an exterior file it is pointed to doesn't exist also means that it should be able to access these files, (although some other behavior I noticed while trying to figure this out makes me think that the script only has access to the parent directory of the compose file).

[itzg]

I understand your confusion, but these are fundamental docker things. The container can only see the files that are mapped into its filesystem. So an existing file must exist within the container.

In the case of this image the primary volume is mounted at /data.

As for mapping parent directory of compose file, that's for you to decide and dictate what host directory to attach. Most of the examples attach a relative directory ./data.

[itzg]

Take a look at https://docs.docker.com/reference/compose-file/services/#volumes

[Firefly7-7]

Ok, so looking at how the image works, it looks like most of the heavy lifting and actual setup portion of the image is done by another of your projects, mc-image-helper. This setup is essentially a series of script calls, which are all determined by variables in ENVIRONMENT. So, if I'm correct, everything in ENVIRONMENT is only processed inside of the container, which cannot access outside files, at all.

However, APPLY_EXTRA_FILES requires specifying an outside file path. Which, because of it being processed inside of the container, it should not have any way of knowing exists, or any properties thereof, and as far as I can tell the only behavior is to create an empty directory. Why?

[itzg]

However, APPLY_EXTRA_FILES requires specifying an outside file path

That's not correct. Paths referenced with that variable must be paths inside the container. A container can't reach outside filesystems unless mapped to a container path.

URLs referenced with that variable are inherently "outside" the container since the intention is to download from some website such as a source code repository.