Skip to content

Added recipe to have an interactive shell when using docker #1967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 4 commits into
base: 6.0
Choose a base branch
from
Open

Added recipe to have an interactive shell when using docker #1967

wants to merge 4 commits into from

Conversation

Thanush-03
Copy link

@Thanush-03 Thanush-03 commented Aug 16, 2025 •
edited
Loading

Issue number
Fixes #1960
Description:
Added documentation for interactive shell debugging when using Docker containers. This provides the Docker equivalent of the bin/instance debug command used in traditional Plone installations.
The new "Interactive shell for debugging" section in the Docker recipes documentation includes:
Multiple approaches for getting an interactive shell:
Using docker exec for running containers
Using docker run for new container instances
Using docker compose exec for Docker Compose setups
Practical examples showing how to access the Plone site and set up fake requests
Safety warnings about using this in production environments.

LINK:
https://6.docs.plone.org/install/containers/recipes/index.html

MESSAGE:
The issue being fixed #1960
Interactive shell debugging documentation was added in Docker recipes page.

📚 Documentation preview 📚: https://plone6--1967.org.readthedocs.build/

@boring-cyborg boring-cyborg
Copy link

boring-cyborg bot commented Aug 16, 2025

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, read Plone's Code of Conduct and Contribute to documentation, as this will greatly help the review process.

Welcome to the Plone community! 🎉

@Thanush-03
Fix CI submodule issues and add interactive shell documentation
a1e3780 
- Remove duplicate documentation directory that was causing submodule errors
- Add submodules: true to CI workflows to properly handle submodules
- Add comprehensive interactive shell debugging documentation for Docker containers

Fixes plone#1960
@stevepiercy
Copy link
Contributor

@Thanush-03 please see Granting permission to publish. We can't accept your contribution without your explicit written permission. Thank you!

@Thanush-03
Copy link
Author

Thanush-03 commented Aug 16, 2025 via email

@stevepiercy
Copy link
Contributor

@Thanush-03 is "Thanush K" your actual full name? I've never seen a surname consisting of a single letter, except for Malcom X.

Also did you test your instructions to make sure that they actually work? If you haven't actually tested the instructions, then please close this PR. Thank you!

@Thanush-03
Copy link
Author

Thanush-03 commented Aug 16, 2025 via email

@Thanush-03
Fix deprecated plone.volto:default-homepage profile references
8e5b9ee 
- Remove references to deprecated plone.volto:default-homepage profile
- Update documentation to recommend content export/import approach
- Add explanatory notes about the profile removal in version 5
- Update Docker example to remove deprecated profile usage

Fixes plone#118
@Thanush-03
Merge branch '6.0' into thanush/1960
d66c92e
@Thanush-03
Copy link
Author

@stevepiercy kindly review this and provide me any changes required

@stevepiercy
Copy link
Contributor

@davisagli, @mauritsvanrees, @ericof, @sneridagh would you please do a technical review of the changes to the documentation regarding plone.volto and the container recipe? Thank you!

stevepiercy
stevepiercy requested changes Aug 30, 2025
View reviewed changes
Copy link
Contributor

@stevepiercy stevepiercy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I only made a few style changes.

This looks really good, with the exception that I couldn't find my bin/instance so couldn't run a debugger. What am I missing?

.github/workflows/build_deploy.yml
Comment on lines +19 to +20
with:
submodules: true
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did you add this? It's not broken and it has nothing to do with the purpose of this PR. Please revert.

Suggested change
with:
submodules: true

.github/workflows/test.yml
Comment on lines +10 to +11
with:
submodules: true
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did you add this? It's not broken and it has nothing to do with the purpose of this PR. Please revert.

Suggested change
with:
submodules: true

docs/developer-guide/create-a-distribution.md
Comment on lines +340 to +342
```{note}
This is the recommended approach for creating example content in distributions.
The old approach of using profiles like `plone.volto:default-homepage` has been deprecated and removed from `plone.volto` in version 5.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@davisagli can I get a confirmation about this change?

Suggested change
```{note}
This is the recommended approach for creating example content in distributions.
The old approach of using profiles like `plone.volto:default-homepage` has been deprecated and removed from `plone.volto` in version 5.
```{versionremoved} `plone.volto` 5.0.0b1
This is the recommended approach for creating example content in distributions.
The old approach of using profiles like `plone.volto:default-homepage` has been deprecated and removed from [`plone.volto` in version 5.0.0b1](https://github.com/plone/plone.volto/blob/main/CHANGES.md#500b1-2024-10-30).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stevepiercy It is correct that the plone.volto:default-homepage profile was removed from plone.volto, but I think it's noise to mention that here. These docs are for someone creating a new distribution, not someone who is updating an existing distribution that might have referenced that profile.

It's incorrect to say that the old approach of referencing content profiles in the distribution is deprecated. Both approaches for creating example content are still supported. It's fine to say that this one is the recommended one (since it requires less configuration).

I don't understand why any of this is in this particular pull request, which claims to be about adding documentation for an interactive shell, which is unrelated to distributions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a separate PR to clean up the outdated references to the plone.volto:default-homepage profile, so that we can focus on the interactive shell docs here.

docs/install/containers/images/frontend.md
Comment on lines +111 to +112
# Note: plone.volto:default-homepage profile was removed in version 5
# Use content export/import instead for example content
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, wait a minute. The ADDONS includes plone.volto==4.0.0a3, and not 5.0.0b1 or later, making this comment very confusing. @davisagli @ericof @sneridagh @mauritsvanrees can I get some clarification on this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a quite old list of version pins which was probably left over from Plone 5 where volto wasn't included. Neither the ADDONS nor PROFILES environment variables should be needed here; the plone-backend image already contains appropriate versions.

docs/install/containers/recipes/index.md
When developing or troubleshooting Plone applications in Docker containers, you may need an interactive Python shell with the Plone environment loaded.
This is the Docker equivalent of the `bin/instance debug` command used in traditional Plone installations.

### Using docker exec
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Using docker exec
### `docker exec`

docs/install/containers/recipes/index.md
setRequest(app.REQUEST)
```

### Exiting the debug console
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Exiting the debug console
### Exit the debug console

docs/install/containers/recipes/index.md

### Using docker run

Alternatively, you can start a new container instance specifically for debugging:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Alternatively, you can start a new container instance specifically for debugging:
Alternatively, start a new container instance specifically for debugging.

docs/install/containers/recipes/index.md
If you have a running Plone container, you can start an interactive shell using `docker exec`:

```shell
docker exec -it <container_name> /bin/bash
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docker exec -it <container_name> /bin/bash

Suggested change
docker exec -it <container_name> /bin/bash
docker exec -it BACKEND_CONTAINER_NAME /bin/bash

docs/install/containers/recipes/index.md
Once inside the container, you can start the Plone debug console:

```shell
bin/instance debug
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there's a step missing before this one. I followed the instructions in https://6.docs.plone.org/install/containers/index.html through "Access your Plone site" to set up the containers. The bin directory has all the usual Plone stuff, but no instance.

docker exec -it plone6-backend /bin/bash
root@9ae16356b1a2:/app# bin/instance debug
bash: bin/instance: No such file or directory

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Within the plone-backend container, the correct command is ./docker-entrypoint.sh console, not bin/instance debug. bin/instance debug would only work with a buildout-based installation, which the plone-backend container does not use.

docs/install/containers/recipes/index.md
Then start the debug console:

```shell
bin/instance debug
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See previous comment. I have no bin/instance.

@github-project-automation github-project-automation bot moved this from New to In Progress in Plone Documentation Aug 30, 2025
davisagli
davisagli requested changes Aug 30, 2025
View reviewed changes
docs/install/containers/recipes/index.md
## Interactive shell for debugging

When developing or troubleshooting Plone applications in Docker containers, you may need an interactive Python shell with the Plone environment loaded.
This is the Docker equivalent of the `bin/instance debug` command used in traditional Plone installations.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are multiple traditions for how to install Plone. It'd be clearer to say buildout-based instead of traditional.

Note, we already have documentation for doing this outside the context of a Docker container in https://6.docs.plone.org/admin-guide/run-plone.html#run-a-debug-console where we call it a debug console rather than an interactive shell. I don't care what we call it but we should be consistent.

docs/install/containers/recipes/index.md
Once inside the container, you can start the Plone debug console:

```shell
bin/instance debug
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Within the plone-backend container, the correct command is ./docker-entrypoint.sh console, not bin/instance debug. bin/instance debug would only work with a buildout-based installation, which the plone-backend container does not use.

docs/install/containers/recipes/index.md

### Accessing the Plone site

Once in the debug console, you can access your Plone site and perform debugging operations:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This information isn't specific to a console that was started in a container. It should go under https://6.docs.plone.org/admin-guide/run-plone.html#run-a-debug-console instead.

@stevepiercy
Copy link
Contributor

@Thanush-03 would you please rebase your branch on main, resolve any merge conflicts, and update your pull request according to the reviews here? Then we can do another review and proceed. Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@davisagli davisagli davisagli requested changes

@stevepiercy stevepiercy stevepiercy requested changes

@mauritsvanrees mauritsvanrees Awaiting requested review from mauritsvanrees

@ericof ericof Awaiting requested review from ericof

@sneridagh sneridagh Awaiting requested review from sneridagh

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
Plone Documentation
Status: In Progress
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Add recipe to have an interactive shell when using docker
3 participants
@Thanush-03 @stevepiercy @davisagli