Fixing docs for ticket and other setup pages

(1) By Dan Shearer (danshearer) on 2020-10-29 16:47:29 [link] [source]

Since we are close to a new release, I'd like to commit fixes to some documentation that is frustrating me right now.

Q: How can I deduce the canonical page for setup items?

It should be possible to work out what the correct page is by looking at the configuration sets in src/configure.c . However what I read there is reference to /ticket (which is the non-setup ticket page) and /skin (which ought to be /skin_setup) . I don't know how configure.c works yet, but for now I'd like to be able to easily read the "configuration set" declarations and (a) navigate the interface for my own use and (b) fix the documentation before release (including tickets and webui.

The docs above refer to two web pages that no longer exist. And I suppose the "Admin" menu has been replaced by assorted other pages such as /setup, navigable from /sitemap?

(This is extracted from my List of Infrequently Asked Questions I am compiling as I do my first public-facing Fossil deployment.)

Dan

(2) By Dan Shearer (danshearer) on 2020-10-29 17:28:33 in reply to 1 [link] [source]

No, mostly this is a matter of having the 's' permission rather than merely 'a', which is documented.

Dan

(3) By Warren Young (wyoung) on 2020-10-29 18:01:50 in reply to 2 [link] [source]

The "Admin" link in the default skin's toolbar once was in fact called "Setup", but I changed it some years back when I realized that about half of what appears on the /setup page is in fact accessible to users with only Admin capability.

I couldn't rename the URL itself without breaking existing links, but if you committed an /admin URL alias for /setup, I don't see why anyone would reject it.

I looked at your documentation links, and they correctly say "Admin", not "Setup". Where is this fix you're saying needs doing?

(4) By Dan Shearer (danshearer) on 2020-10-29 18:21:12 in reply to 3 [link] [source]

I forgot that capability S implies capability A, but not the reverse.

The overall problem I'm solving is an efficient way of creating: one web site maintained in a fossil repo, where the site is relevant to 3 or fossil code repos, where the repos have admin users in common and policies in common. I've written a script that creates the repos in a reasonable way, and now I'm scratching my head on questions like "ok, so how do I enable the forum and search in a consistent manner?". Stephan's website is one of several I found that more or less do this already.

At which point I went off looking for the relevant web pages for setting up the forum, checked that there wasn't an equivalent command line, decided that it needs to be done in a point-click manner, and that's as far as I have got.

As to the docs, while there is some scope to be clearer about S and A permissions, I don't actually think there are outright errors in the documentation and display messages.

Thanks,

Dan

(5.1) By Warren Young (wyoung) on 2020-10-29 18:58:12 edited from 5.0 in reply to 4 [link] [source]

there is some scope to be clearer about S and A permissions

Clearer than this?

EDIT: Also, I still fail to see these "references to two web pages that no longer exist."

(6) By Alfred M. Szmidt (ams) on 2020-10-30 08:16:09 in reply to 4 [link] [source]

This seems interesting, could you share the script you’ve come up with? I’m also in a situation where I have one site and several sub-projects.

(8) By Dan Shearer (danshearer) on 2020-10-30 14:04:41 in reply to 6 [source]

Alfred M. Szmidt (ams) on 2020-10-30 08:16:09:

This seems interesting, could you share the script you’ve come up with? I’m also in a situation where I have one site and several sub-projects.

Here you are. The idea is that you specify users and repos, with the ability to have a list of users that are in one repo but not others (in my case, where one of the repos is for documentation only.)

On the one hand it seems trivial (why bother for so relatively few commands, and for something that is most likely a one-off?) but on the other, having a handful of repos in the same family that aren't consistent would just be annoying. This script plus "fossil init --template" would solve a good deal of it, but as you can see below --template doesn't feel very satisfactory.

Dan Shearer

#!/bin/bash

# This incomplete script is for initialising a group of Fossil repos where
# there are shared admin users and shared policies across the repos. Unsolved
# issues remain for the gui-only configuration items. Suggestions gladly received.
#
# Dan Shearer
# dan@shearer.org
# 28th October 2020

NewSuperUser(){
	local u=$1
	local email=$2
	local pass=$3
	local repo=$4
	fossil user new $u $email $pass -R $repo
	fossil user capabilities $u sa -R $repo # Setup+Admin
}

NewRepo(){
	local r=$1
	local repo=$r.fossil
	local domain=$2
	local numusers=$3
	local email=$1-root@$domain
	local emailrobot=$1-robot@$domain
	local mx=mx.$domain

	fossil init $repo --admin-user $r # NB this command cannot set email details
	fossil user default $r -R $repo

	local i
	for ((i=1;i<=$numusers;i++)); 
	do 
		local temp=User$i
		NewSuperUser ${!temp} $repo
        done

	# The following ignores what is or is not the default. It's about 
	# thinking through features we want in this multi-fossil deployment

	fossil settings email-admin $email -R $repo   # for inbound administrative mail
	fossil settings email-self $emailrobot -R $repo # for outgoing mail
	fossil settings email-send-method relay  -R $repo
	fossil settings email-send-relayhost $mx -R $repo
	fossil settings email-subname [$1] -R $repo
	fossil settings main-branch trunk -R $repo #not usually true for git imports
	fossil settings redirect-to-https -R $repo 2 # Just in case the web server/proxy doesn't
	fossil settings self-register off -R $repo # Disallow 

	fossil remote off -R $repo # This is top of the tree, others pull from us

	# fossil ui --page setup_uedit?id=1 ... add email for the owner user 
	# fossil ui --page srchsetup ... enable search in a consistent way across all repos
	# and web pages for:
	#  - setting up the forum
	#  - setting common skin elements 
	#  etc etc
	#  
	#  It is possible that we just have to use "fossil init --template"
	#  for all of these items and forget setting things up programatically.

}

# List of users that may be initialised for a repo, applied from the top
# (which is $User1) down to the number specified in the NewRepo call.
User1="kirstysmith kirsty@example.org KPASS1234567"
User2="nguyenthidinh nguyen@example.org NPASS1234567"
User3="jimmyonerepo jimmyonerepo@example.org JPASS1234567"

RepoPass="ROOTPASS1234" # Overwrite generated password for --admin-user in all repos

NewRepo firstrepo example.org 2
NewRepo secondrepo example.org 2
NewRepo thirdrepo example.org 3

(9) By Dan Shearer (danshearer) on 2020-10-30 16:28:59 in reply to 8 [link] [source]

Dan Shearer (danshearer) on 2020-10-30 14:04:41:

This script plus "fossil init --template" would solve a good deal of it, but as you can see below --template doesn't feel very satisfactory.

I discovered the "fossil sql" command, which looks like it will help.

For example:

fossil sql "insert or replace into config values ('project-name', '${r^}', now() );"

So it's a matter of poking about in the Fossil source to figure out how to get the desired effect.

I recommend fossil help sql, there's a lot in it.

Dan Shearer

(7) By Stephan Beal (stephan) on 2020-10-30 08:22:08 in reply to 4 [link] [source]

and now I'm scratching my head on questions like "ok, so how do I enable the forum and search in a consistent manner?". Stephan's website is one of several I found that more or less do this already.

To clear up any potential misconception: that site is maintained in fossil but it's not served from fossil. The search field on the left is not fossil's, but works via a custom CGI accessing an FTS5 database built from the "content parts" of the pages on the site (the menu, header, and footer are all pasted together with per-directory content parts by a build process, and only those generated files get uploaded to the web server).