Docs and examples update, again
tzerber opened this issue · 5 comments
Using this issue as placeholder.
I am going to update the Readme / docs / examples for the docker compose syntax and file naming according to Docker and Docker Compose requirements. I see there's an open PR for the removal of the "version" parameter, but that's not enough. I had this idea when I updated the examples last time, but didn't had the time for it, now I do. I also plan on updating the example MariaDB from 10.6 to 10.8.2 based on few years production experience, and add redis to the default examples because just like last time - I see a lot of people ignoring the warning that this repository is for expert use, clone the examples section as-is and then try to figure out why it is not working properly.
maybe you consider extensive example I published shortly on support forum
https://help.nextcloud.com/t/nextcloud-docker-compose-setup-with-notify-push-2024/186721
it is harder to follow and uses advanced methods like secrets and UID but results in very complete and secure system (traefik compose example will follow)
The idea of the examples is to be a simple, minimalist way of getting Nextcloud non-aio up and running. The repository is for advanced, a bit more experienced users, unlike tha AIO variant that is designed for the most easy way of using NC in Docker but the examples themselves (as show by history here) should be as simple as possible. And J0WI is also correct, we should not make assumptions on end-user's setup,
I've read your post and it looks very good, but if we do something like this here, it might create a lot of confusion over new/inexperienced users, and that is something we should avoid.
I can't exactly follow your arguments. while it is true AIO serves the needs of beginner and lazy users better, this "community image" is expected to address experienced users and for this reason I don't get why examples should remain simple.
I think AIO docs could be good inspiration: they host sub-categories covering special requirements e.g. reverse proxy, "manual AIO" installation etc.
From my experience examples provided now are somewhat incomplete e.g. non-root is not shown (neither documented), reverse proxy is missing. Users trying to build a complete system must rely on external sources and tutorials. I would appreciate kind of full example showing all the possibilities of the image. Definitely really complex scenario must not be the first one, but another "complex"/"advanced" example with separate read-me and maybe reverse proxy examples would really help to setup the image in a good way. Let me know if I can support writing such an example or user docs.
I can't exactly follow your arguments. while it is true AIO serves the needs of beginner and lazy users better, this "community image" is expected to address experienced users and for this reason I don't get why examples should remain simple.
Because for whatever reason most google results points somewhere in this repository, and most beginners just use this repository instead of the AIO one, completly ignoring/missing the warning that his is not for beginners (his is purely my observation, backed by a bunch of issues in the issues section). Same apply for everyone trying to use the FPM image in some random setup where the setup differs from the "default" one. You can probably add most of RPI users to this group as well.
I think AIO docs could be good inspiration: they host sub-categories covering special requirements e.g. reverse proxy, "manual AIO" installation etc.
I agree here, but it seems nobody has the time to make 25 or so different examples including apache/nginx/caddy/traefik/other random web-servers/insecure/self-signed certs for private environments and the combination of those. And then keep them up to date.
From my experience examples provided now are somewhat incomplete e.g. non-root is not shown (neither documented), reverse proxy is missing. Users trying to build a complete system must rely on external sources and tutorials. I would appreciate kind of full example showing all the possibilities of the image. Definitely really complex scenario must not be the first one, but another "complex"/"advanced" example with separate read-me and maybe reverse proxy examples would really help to setup the image in a good way. Let me know if I can support writing such an example or user docs.
The problem (in my view) is that there are a bit too much options. A lot of people prefer traefik over nginx for their reasons. A lot of other people prefer nginx over apache2. Add Caddy, swarm, kubernetes, etc etc. I agree with devs here on the point where we should not make assumptions. A full example would include quite a lot of stuff that has nothing to do with Nextcloud itself. Some basic assumptions (see the PR about Redis) can be made, because effectively everyone uses them. Not so long ago a random guy here asked for a combo with nginx-proxy-manager, and this is somewhat different from the nginx-proxy, and i wrote him an example. It was for NC28 and it's now a bit outdated, and I don't really have the free time to update it without legitimate reason.
That's basically my logic, and i have the weird feeling it's the dev's logic as well.
Because for whatever reason most google results points somewhere in this repository, and most beginners just use this repository instead of the AIO one, completly ignoring/missing the warning that his is not for beginners (his is purely my observation, backed by a bunch of issues in the issues section)
In my eyes this a good point to provide complete working examples rather only a skeleton which throws many setup warnings this beginners can not handle at all.
A full example would include quite a lot of stuff that has nothing to do with Nextcloud itself. Some basic assumptions (see the PR about Redis) can be made, because effectively everyone uses them.
OK, now we are really close to each other.. This external stuff required to run Nextcloud should be included in the example. e.g. questions regarding cron keep coming in the forum - "official" working example would help a lot. and after adding cron and in my eyes highly recommended notify_push and the only remaining addition in my guide is imaginary..
The problem (in my view) is that there are a bit too much options.
yes I agree. but covering some common options would help already. IMHO "external" integration like reverse proxy are easier to maintain as the connection is always the same. you have defined interaction in this particular case HTTP- header and you only need to show how to setup the proxy to add right headers - the system behind it remains unchanged and ideally same reverse proxy example works for both Apache and FPM variants.