Discuss: Should docker compose run detached in usage guides?

[coderabbitai]

Context

In PR #367, a question was raised about whether docker compose up should be run in detached mode (--detach) in our usage guides.

Current Situation

The current approach uses docker compose up without the --detach flag, which runs containers in the foreground. This means:

• Users see service logs in real-time
• The terminal is blocked, requiring users to open a new terminal for subsequent commands
• Users may not realize they need a new terminal to continue the guide

Proposed Alternative

Using docker compose up --detach would:

• Start services in the background
• Allow users to continue in the same terminal session
• Make the walkthrough more seamless and executable in a single shell

Discussion Points

1. Should we standardize on detached mode across all usage guides?
2. Is there value in showing logs during startup for debugging/learning purposes?
3. Should we provide guidance on viewing logs separately (e.g., docker compose logs -f)?
4. What's the best user experience for documentation walkthroughs?

Please share your thoughts on the optimal approach.

References

• PR: Usage guides: Use {Docker,Podman} Compose where applicable #367
• Comment: Usage guides: Use {Docker,Podman} Compose where applicable #367 (comment)
• Requested by: @amotl

cc: @surister @michaelkremmel @bmunkholm

[michaelkremmel]

Thank you for bringing up this topic.

TL;DR

1. It depends on the error handling if something goes sideways (see my questions below), but in general it sounds like a good option.
2. Yes, it helped me identify CrateDB fails to start on Windows with -Cdiscovery.type=single-node crate#18378
3. Yes, if detached mode is used, we should do it
4. If everything works well, being able to go through everything in one terminal sounds great. Still, as mentioned below, other services in the tutorials are behaving similarly to how CrateDB does today. Therefore, I suggest that, where possible, we initiate them all in the same way, so that they do not block the terminal. If this is not possible, we should mention it in the tutorial to open a new terminal.

Questions regarding point 2
a) Since I've encountered some issues resulting in crate/crate#18378: What would have been the behaviour in the proposed scenario you have described?
b) Would the service start and then, after failing, just stop without any error message?
c) Would I need to run docker compose logs -f?
d) Where would I learn about this command (in each and every tutorial)?

Context and my opinion
While I went through the tutorial, I encountered the issue with the blocked terminal. Seeing the logs helped me easily identify crate/crate#18378, and I could find a workaround. I don't know how the behaviour would have been with detached mode, hence my questions above.

If everything works well, the proposed alternative sounds great. The question is what to do when something is not working as expected. The blocked terminal itself is not a significant issue because other services in the tutorials I went through behave similarly, resulting in four or so terminal tabs being open simultaneously in the end. However, if we were to mention it in the tutorial, "Now open a new terminal ...", this could be enough, I guess, while the proposed solution is way more elegant and sophisticated.

[surister]

I don't think we should. We are not in the business of teaching users how to use docker or their terminal, we must assume that if they are reading a guide on how to run CrateDB in docker, they must be somewhat capable in docker, otherwise this rabbit hole never ends and we should also teach them about I/O, logging, process handling in unix systems, how to install docker, how to install a terminal... etc

[amotl]

My opinion is also that we don't necessarily need to use --detach here, to give users the opportunity to follow the log outputs easily. I think your evaluation encourages this approach?

When validating a tutorial the other day, I encountered the issue with the blocked terminal. Seeing the logs helped me easily identify crate/crate#18378, and I could find a workaround.

I also agree we don't need to educate people about using Docker, following the tendency to deprofessionalize the company based on the assumption our tech and docs would be too complicated and that we should make things easier for beginners. Instead, we should explain and convey CrateDB's topic domains well on a professional level, in order to attract the right audiences.

[amotl]

If you think all is fine, let's close this ticket now. Otherwise, please let us know if you think we should additionally educate users about:

• That the process blocks when not using --detach, and that they will need to use another terminal session.
• The docker compose logs -f command to inspect the logs in all situations.

[michaelkremmel]

Yes, I agree. I'm sorry, I only saw now that Coderabbit created the ticket; I thought you, @amotl, suggested the solution. I'll close the ticket.

[amotl]

The question was an honest one coming from me, to probe if we share different opinions about this. I just used CodeRabbit to save keystrokes. Thanks for your feedback.