Item1752: PROXY is inadequately documented

pencil
Priority: Normal
Current State: Closed
Released In: 1.0.6
Target Release: patch
Applies To: Engine
Component: Documentation
Branches:
Reported By: MichaelTempest
Waiting For: Main.MichaelTempest, Main.KennethLavrsen
Last Change By: OlivierRaginel
{PROXY}{PORT} and {PROXY}{HOST} are "expert" settings in configure. You have to click "I have read all of the documentation" before you can see those options. However, it is hard to find any documentation for these settings, outside of the description of the settings themselves.

It is also odd that these are "expert" settings. I expect it is common for Foswiki to be installed behind a proxy server in a corporate environment, so a system administrator new to foswiki should be able to set this up. That means - not "expert".

IncludeTopicsAndWebPages says to set a proxy in DefaultPreferences. It should not, since that topic should not be modified as it is part of the distribution.

-- MichaelTempest - 18 Jun 2009

you only need to set this if

  • you are behind a firewall with a proxy
  • and you allow includes of external webpages
  • Or you need to install extensions through the firewall

I would say it is an expert setting

I would more think about a better way to reveal the expert settings. That button far away at the top is not obvious. Maybe we need something like a twistie alike thing in each section of configure.

Another thing we should consider is an installation wizard that takes you through settings step by step and open up additional settings based on simple questions.

-- KennethLavrsen - 17 Jun 2009

I agree that we need a better way to manage expert settings and installation. That will take time. I have noticed that this proxy question does come up from time to time, so I think a short-term solution is needed.

The combination of "behind a firewall with a proxy" and "need to install extensions through the firewall" sounds typical of a corporate environment, and I would have thought that a proxy setting is well within capabilities of someone who can install Foswiki. (Except, perhaps, a debian-package install, and that installer attaches a "do not use" warning to "Find More Extensions" anyway.) Which is why I didn't think it should be expert.

... But, I can live with it staying an expert setting so long as there is documentation that points to those settings. Right now, you have to click "I have read all of the documentation" to find out that these settings even exist.

Some suggestions for the short term:
  • Add something to the "Find More Extensions" and {INCLUDE}{AllowURLs} descriptions to say, at least, that there are such settings.
  • Add something to the InstallationGuide.
  • Change IncludeTopicsAndWebPages to refer to the settings in configure, instead of suggesting a change to DefaultPreferences

-- MichaelTempest - 19 Jun 2009

From the IRC log:
[06:15]  Lavr: I made an alternate suggestion to making settings non-expert in  http://foswiki.org/Tasks/Item1752
[06:17]  Reading
[06:19]  Actually! I am thinking. Our INCLUDE feature - does it support the proxy? I think it does. But not well.
[06:19]  We still lack implementing authentication.
[06:19]  We have authentication for the proxy for configure but I believe it is still missing for INCLUDE.
[06:20]  Which is actully the reason why the settings are still regarded as expert. The minute we get authentication included for INCLUDE all the proxy settings should be non-expert.
[06:20]  I think TWiki implemented the code for INCLUDE and we never followed up with that.
[06:21]  Something we for sure should have in 1.1

Just updating documentation, for now.

-- MichaelTempest - 20 Jun 2009

Bouncing an old task is bad, but I just wanted to get reactions to this...

What Lavr is saying is wrong. Foswiki core code since day 1 included this feature. {PROXY}{HOST} and {PROXY}{PORT} are shared for all HTTP requests (afaics from the code), and it works just fine for many users, as Michael's documentation updates show.

So, why wasn't this setting moved out of the expert setting, as many user including IngoWolf today are looking for it?

I'll keep this task as closed, as I do not want to interfere with the release process, but I hope you guys will get notified anyhow.

  • Ok, as Michael came back to me on IRC to enlighten me on what Lavr said, in fact, we have Auth also for a long time, you just set : http://user:pass@proxyhost.domain.tld:port
  • So it should be documented and moved out of Expert, right?

-- OlivierRaginel - 11 Jan 2010

I have not tested this but yes, if we have authentication for INCLUDE also then it should be non-expert.

I can test it as work.

Please open a new report. If it is just to unexpert and docu then it can make it to 1.0.9.

If the feature is missing and needs implentation then it is 1.1

Please please make a new bug item for proper trace in release notes

-- KennethLavrsen - 11 Jan 2010

Damned, I overlooked the code, and in fact the user:pass parsing is done for any other URL, but NOT for the proxy.

Therefore, this cannot make it to 1.0.9, but I will try to code this for the next release. I've opened Item 2623 to follow up on this. Done it once to re-use a task to commit something, won't do it again smile

-- OlivierRaginel - 12 Jan 2010
Topic revision: r24 - 12 Jan 2010, OlivierRaginel
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy