Dear Maintainer,

I rant into issues following /usr/share/doc/radicale/README.Debian following issues. I hope my comments can reduce the number of support requests. I dumped README.Debian  below with feedback that I hope is helpful. I'm happy to polish up the text and submit a formal patch if you fundamentally agree with my comments.

Additionally, the other README files, which are pulled from github, should probably reference README.Debian or be replaced with README.Debian. README.md is meant as a github landing page and might confuse  new users who should be reading README.Debian.

README.Debian:

This can probably be improved by rewording to 'i.e. expects a WSGI server to resolve ${REMOTE_USER}'. auth/remote_user.py states that this mode only supports  an 'external WSGI server.' A new user might be fooled into thinking that they  can graft their own bash script to handle this variable, for example.

This line should be removed and (possibly) replaced with something to the effect of "Radicale's default settings work. If you need to customise the configuration, see DOCUMENTATION.html for instructions."

In my first attempt with Radicale, this line confused me because I didn't know what I 'needed' to 'adapt', and the official documentation gave me instructions that conflict with the WSGI setup.
external

Can't this be automated in debconf with a "set up and enable radicale for (1) apache; (2) nginx'? Furthermore, on almost every configuration, this will have to be run as a superuser and might want to be indicated, unless it's not standard Debian practice to do so and make the user figure it out from "permission denied".

Apache (at least my installation) doesn't enable ssl out of the box. `a2enmod ssl; a2ensite default-ssl` (or graft default-ssl into apache2-vhost.conf) to reduce new user frustration.

For simplicity, consider changing _DOMAIN to 'localhost' for a local set-up. 'example.org' confused me into thinking that Radicale and/or SSL won't work without a domain name, so changing _DOMAIN to 'localhost' may be easier.

Although, in general, /etc/apache2/.../000-default.conf should probably set a _DOMAIN variable for this configuration to reference.

And perhaps add something to the effect of "Go to https://events.example.org <http://events.example.org> (or https://events.localhost/ <http://events.localhost/>" to test Radicale (since the default installation and documentation points users to localhost:5232, which may be confusing) and something to the effect of 'log in with the same credentials you use to log into your computer' or something to that effect.

I didn't test the sysV setup, but I don't see any reference to the systemd
enabling here.

I'm happy to work on the phrasing to improve this for new users like me and reduce bug reports.

Hi Borden,

Quoting Borden (2022-08-19 23:27:14)

I am sorry you ran into trouble, and appreciate your attempt at helping
improve the situation.

Comments under each quoted section below...:

Upstream documentation files are included when they contain information
relevant also to some Debian users.  Common packaging practice in Debian
to document deviations from upstream in a README.Debian file rather than
patching upstream documentation files.  I disagree that only purpose if
README.md is when served at github.com, I see some value in including it
as the introduction communication from upstream.

The target audience is not only new users, also experienced users.  I
disagree that information confusing for new users should be removed.
Should be obvious that not any bash script is acceptable, but ok: The
word "WSGI" is now added to further disambiguate.  Thanks!

Good point.  Now rephrased to ", using the file /etc/radicale/config as
main configuration file." which should provide the intended hint about
the file location without being perceived as an instruction of needed
action.  Thanks!

Yes, that is possible - see also the notes on dual-use in the TODO file,
which I suspect needs implemented first.  Implementing this will be extra
work that I am not sure when (if at all) I will take time to do on my own -
a patch for a draft proposal will be appreciated!  I have spawned a
separate bugreport to track this issue on its own: Please post followups to
that newly created bugreport instead of the originally filed one.

extended to also enable ssl module, and added this explicit note:

  (details on vhost and SSL/TLS certificate setup is not covered here)

No, TLS generally needs a specific hostname.

Documenting vhost and TLS certificate handling belongs to frontend web
service setup.

No, I consider that too detailed documentation, that I will not take
responsibility for keeping up-to-date: Upstream has fine documentation,
but indeed you need to be able to understand where to fill in your own
domain name instead of "localhost", because Radicale is flexible and
supports setups other than the commonly sensible ones.

I encourage discussing upstream how possibly their documentation can be
improved.

That section clearly says that it is discouraged and untested.  If you
want that section expanded then please also try convince me why it
should not be discouraged.


Kind regards,

 - Jonas

Hi,

while preparing another related bugreport I reread this bug and its clone:

#1017764 radicale: enable apache2/nginx integration using debconf
#1017824 radicale: Readme and uwsgi improvements

I think you closed the wrong bug in radicale (3.1.8-2):

    * improve README.Debian;
      closes: bug#1017764, thanks to Borden

If I'm right the best way forward may be to unarchive the first bug and
switch both bug titles (I may do this):

unarchive 1017764
retitle 1017764 Readme and uwsgi improvements
retitle 1017824 enable apache2/nginx integration using debconf
archive 1017764

Greets jre