needs clear difference between pwd.yml and compose.yaml - in documentation

[asbharathinesar]

The document is not clearly differentiated between the pwd.yml, compose.yaml in the documentation- it takes about a week to find the difference

The real difference we found:
compose.yaml - for stock ERPNext only (bench is locked)
pwd.yml - the full open version for adding custom apps

[asieftejani]

as far as i know its the opposite
@DanielRadlAMR your input pls

[DanielRadlAMR]

The pwd.yml file stands for Play With Docker — it’s a simplified configuration meant to help you get ERPNext up and running quickly (Play With Docker). It’s designed for quick, disposable demo setups — not for production or extended development.

The compose.yaml file, on the other hand, is the more flexible and complete setup. It’s meant for proper deployments and can be extended to include custom apps or other services. However, it does require a bit more understanding of Docker and Frappe to configure correctly.

If the documentation doesn’t make this distinction clear, feel free to open a PR to improve it — clarifications like yours help a lot of new users.

[DanielRadlAMR]

PS: I started working with frappe_docker about a year ago, and I completely understand the struggle you’re describing. Back then, it wasn’t clear to me how to get started — the documentation had plenty of information, but there was no clear “red thread” guiding you toward a successful deployment. You really need a basic understanding of both Frappe and Docker to get everything running smoothly; it’s hard to just follow the docs step-by-step and expect success without that background.

The documentation has improved since then — mostly in quantity, though not yet enough in quality. That said, there are currently some open PRs aimed at improving the docs, especially for new users. I’d be happy to invite you to share your input or even contribute your own improvements!

[anderwm]

I think I am on this same struggle bus. I keep going around in circles trying to derive my "right way" to build a production/test/development environments. It seems the documentation is a little muddled from older ways of doing things and I can't decide if I should do the docker compose overrides, docker-bake, or be running bench myself in a one off container. Moreover, it isn't clear which image/images actually have bench so I can use it to install the app. Are we kind of stuck in the middle between architecture changes?

[asieftejani]

or be running bench myself in a one off container

@anderwm have you tried a one-off container... do you bake everything or you install the git/node/python/bench
does everything work as expected (especially bench get-app)
I have always wanted to try it out but never got around to it

[anderwm]

or be running bench myself in a one off container

@anderwm have you tried a one-off container... do you bake everything or you install the git/node/python/bench does everything work as expected (especially bench get-app) I have always wanted to try it out but never got around to it

No, I haven't tried it yet...so far I was just reading the tea leaves to try and determine my options. I see no reason why you couldn't do it. However, it's clear that isn't what is intended by the authors of this repo. The intent seems to be that the (production) container is immutable after building with whatever apps you built it with. I think (at least at first) I'm going to go down the route of building with images/layered/Containerfile. I may do some all in one thing for a development container.

[asieftejani]

Okay enjoy your learning curve... let me know if the one container thing works - according to ChatGPT it defeats the purpose of docker containers from frappe's point of view but i think for us users/developers its perfect as it can give us the vm experience (bench commands specifically) with the advantages of docker (run anywhere, quick start, light-weight, etc..)

[DanielRadlAMR]

I’m not completely sure I understand your main difficulty, especially the part about the one-off container.

From what I’ve gathered, the main confusion seems to be about which Docker approach to use for setting up your environment, since several different Docker “technologies” are involved here:

• docker-bake
  Used to build the containers published on Docker Hub. I don’t really see why you would need this for personal use. (Bake itself uses the Dockerfiles defined in the /images folder.)

• pwd.yaml
  This is a single Compose file used to spin up quick, disposable demo setups with Frappe and ERPNext installed. It’s great for trying things out or exploring the software, but not intended for production or extended development.

• Compose with overrides
  This is the recommended way to build a custom Compose setup for production.
  See: https://github.com/frappe/frappe_docker/tree/main/docs/container-setup

Regarding your question about which containers include bench: since bench is required for every Frappe installation, almost every container mentioned here already has it installed. You’re correct that you are not intended to “develop” inside a container in a production setup. Instead, you should build containers according to your needs — and if those needs change, the container (and thus the image) should be rebuilt and redeployed.

For development, use devcontainers. There you can freely install apps and modify your environment as needed.

About the “one-off container”: what exactly do you mean? A single container that includes everything, including the database? That’s not how containers are meant to be used. The principle is one container per service. Use a Compose file to combine multiple containers rather than putting everything into one container.

Let me know if this was useful or if you have a different view on any of the points.

[anderwm]

I think after consuming all of the documentation, it is better than I was thinking above. When setting up these types of things now days I lean on AI to get me started/not make me read everything and in this case it was pulling me in all kinds of (probably old) directions. However, once I found container-setup I started to understand the workflow.

The other thing tripping me up is that I prefer to have the data I will ultimately back up mounted on the host, but in doing this it was somehow clobbering the site data coming from the docker build and I could never get it bootstrapped. In the end I had to do it in docker volumes (like the compose files you have) to get everything set up and then copy the docker volumes over to the host and switch it to a bind mount. I'm sure there is some way to do host mounts from the beginning, but I kept running in to difficulties.

Sorry if I came off as overly critical (especially not having read enough), if anything maybe container-setup should be called something like "Production Build Instructions" and show on the top level readme. However, would just be for goof balls like me who were trying to move too fast.

Thanks for the reply

[asieftejani]

my definition of "one container" - start with a fresh OS (frappe prefers debain) then install everything one by one just like you would do in a vm ... rather than bake and create layers
just as an experiment - just was curious if erpnext would work in such a container