docker: Improve default run behavior

[cejohnson]

Updates the default docker run behavior to print version text, basic usage information, and a link to more information. This has no impact on anyone already providing custom commands to the container.

Currently calling docker run without a command results in an error (see #5592), this PR aims to improve the "out of the box" experience for new users without impacting any current workflows.

Current behavior:

➜  ~ docker run osgeo/grass-gis:releasebranch_8_4-alpine
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "$GRASSBIN": executable file not found in $PATH: unknown

Run 'docker run --help' for more information
➜  ~

New behavior:

➜  ~ docker run grass-gis
GRASS 8.5.0dev
Geographic Resources Analysis Support System (GRASS) is Copyright,
1999-2025 by the GRASS Development Team, and licensed under terms of the
GNU General Public License (GPL) version >=2.

This GRASS 8.5.0dev release is coordinated and produced by
the GRASS Development Team with contributions from all over the world.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

Usage:
 - Shell: docker run -it [IMAGE] /bin/bash
 - GRASS: docker run [IMAGE] grass [...args]

See https://github.com/OSGeo/grass/blob/main/docker/README.md for more information.
➜  ~

Edits to the output usage information are welcome.

[echoix]

You are right about the problem of using the docker image without a command.

In your PR, you are helping us understand what is going on.

If you look at the differences between exec and shell forms of EXEC in https://docs.docker.com/reference/dockerfile/#cmd, you are changing from exec to shell form, not much more. So, the same problem is still there (but with some nice help).
The differences between both are explained further at https://docs.docker.com/reference/dockerfile/#shell-and-exec-form, containing what doesn't work the same for the variable substitutions for example.

So, the real problem could be fixed by defining an entrypoint + cmd, so that just launching the image would get you in the grass shell; probably the expected usage. Moreover, grass in the terminal is already a shell (with setup done), so it is usable as is in an interactive session. Entrypoint can be overriden on the command line, so it's not an issue here.

https://docs.docker.com/reference/dockerfile/#entrypoint
Also read this section: https://docs.docker.com/reference/dockerfile/#understand-how-cmd-and-entrypoint-interact

So, as you seem to be a user of applications running through docker, and have an idea on what the expected usage for grass would be like, I suggest, after reading the above, to decide on what entrypoint should be used, either:

• "grass", which launches a Python script and sets the shell. It is what is in the bin.*/ folder when compiling locally, https://github.com/OSGeo/grass/blob/9a56016648b645e2d365e0530fd0e298bb97aed0/lib/init/grass.sh
• A new custom entrypoint.sh, stored in the docker/ folder, that would be copied into the image. Would be needed if something more advanced or complex than what we already have.

After that, it would be nice to have the relevant documentation and examples to show the new simplified approach, without having to define the command directly.

[wenzeslaus]

Or just plain, not GRASS, shell?

[cejohnson]

@echoix thanks for the detailed response. As background I am actually not a GRASS user at all, I just currently work at NCSU and @wenzeslaus asked me to take a look at your Dockerfiles to see if I had any recommendations. On the whole I did not, other than observing that the default CMD errored. As a complete neophyte to GRASS I had to do a little digging to figure out exactly what was going on, hence this PR to print out some basic usage information. As to the exec vs shell debate, in this case since no one is using the default CMD anyway I figured it didn't really matter and being able to run multiple commands was convenient.

That being said, I have no idea how these containers are generally used. I had thought they might be used in an automated fashion such that someone would launch a container with the appropriate data and command and let it run its course, but it sounds like terminal access is more likely?

I would say the best solution depends on your priorities and/or target audience. Messing with the ENTRYPOINT could have advantages but may break things for current users if they need to override it. Using grass as the ENTRYPOINT/CMD is probably convenient, but you do have to have some idea of what you're doing regarding volumes, env variables, and arguments for it to work; whether that's a problem is debatable. I suspect complete newcomers are likely to run into issues, but the correct place to address that is likely the documentation.

Overall I'm inclined to agree with @wenzeslaus that starting a plain shell would be the simplest and least impactful approach to getting a successfully running container if that's the goal, but ultimately I don't have a personal stake here.

[wenzeslaus]

As to the exec vs shell debate, in this case since no one is using the default CMD anyway I figured it didn't really matter and being able to run multiple commands was convenient.

My question is whether it is something which other containers (from other software) are using, in other words, how common it is to print usage with the default command.

That being said, I have no idea how these containers are generally used. I had thought they might be used in an automated fashion such that someone would launch a container with the appropriate data and command and let it run its course, but it sounds like terminal access is more likely?

From my experience it would be both, because while the goal might be full automation, the way to get there and discover problems would be interactive shell.

I would say the best solution depends on your priorities and/or target audience. Messing with the ENTRYPOINT could have advantages but may break things for current users if they need to override it. Using grass as the ENTRYPOINT/CMD is probably convenient, but you do have to have some idea of what you're doing regarding volumes, env variables, and arguments for it to work; whether that's a problem is debatable.

That's what is not clear to me. What may break and when it requires override.

...ultimately I don't have a personal stake here.

Which is totally fine as I my goal is to get as 3rd party and/or beginner review. (Sort of "my colleague/customer asked me to run their GRASS stuff in the cloud" scenario.)