Adding a Repository

How to put a new repo on fossil.craftdesign.group. Five commands, then apply.py does the rest: skin, Bone Hive logo, home page, public access, and the card on the landing page.

Everything happens on the server as dmestas. <name> is the URL slug, so keep it lowercase with hyphens.

1. Create the repository

fossil init /var/fossil/repos/<name>.fossil
fossil user new dmestas dmestas /var/fossil/repos/<name>.fossil

To host an existing project instead, skip init and copy its .fossil file into /var/fossil/repos/. Git projects are mirrored rather than copied, see Mirrors below. zit repositories cannot be read by Fossil directly: serve them with zit serve --port 8899 and fossil clone http://localhost:8899/ <name>.fossil to get a Fossil file.

Also set the name shown in the title bar and on the landing page, and the one-line description used as a fallback:

fossil config -R /var/fossil/repos/<name>.fossil set project-name <name>
fossil config -R /var/fossil/repos/<name>.fossil set project-description "What this repo does"

2. Write the meta file

/var/fossil/repos/<name>.meta drives the landing-page card and the public access policy. One value per line:

Line	Meaning	Default when missing
1	Icon: a name from the list below, or an emoji	package
2	Description shown on the landing page	project-description
3	Fossil capabilities for nobody (not logged in)	jh (read wiki only)
4	Capabilities for anonymous (clicked "Anonymous login")	same as line 3

printf 'package\nWhat this repo does\nghoj\n' > /var/fossil/repos/<name>.meta

Icons. Names map to SVG files in /var/fossil/skin/icons/ (Phosphor duotone, MIT licensed). Current set: bone, broadcast, git-diff, hammer, hard-drives, package, plugs-connected, scroll, swatches. To add one, pick an icon at phosphoricons.com, download its Duotone SVG into that directory as <name>.svg, and use that name.

Access. Common capability strings:

• jh private: visitors can read the wiki, nothing else
• ghoj public read: files, timeline, wiki, tickets
• ghoj2 as above plus reading the forum
• ghoj23 on line 4 lets anonymous users post to the forum, with posts held for moderation (this is what zit uses)

The full list is at /<name>/setup_ucap_list on any repo. Lines 3 and 4 are re-applied on every apply.py run, so they are the source of truth for public access; changes made in the web UI get overwritten.

3. Create the home page

apply.py sets the repo's home page to the wiki page named Home, or index if there is no Home. Create one before running it (the extra "index" title is hidden by the skin, so start the page with the real heading):

fossil wiki create index -mimetype text/x-markdown \
  -R /var/fossil/repos/<name>.fossil << 'WIKI'
# <name>

What this repo does.

## Clone

    fossil clone https://fossil.craftdesign.group/<name>/ <name>.fossil
WIKI

A repo that already has a README.md can use that instead: fossil wiki create index -mimetype text/x-markdown -R ... < README.md.

4. Join the login group

One login works across every repo on the server. Join the group through any existing member:

fossil login-group join /var/fossil/repos/zit.fossil -R /var/fossil/repos/<name>.fossil
fossil login-group -R /var/fossil/repos/<name>.fossil   # lists the members

Because of this, the new repo's dmestas user needs no password of its own.

5. Apply

python3 /var/fossil/skin/apply.py

For every repo this installs the skin (CSS, header, footer), the Bone Hive logo, sets nobody and anonymous capabilities from the meta file, and sets the home page if it isn't set yet. It then regenerates the repo grid on the landing page. It is safe to run as often as you like.

The repo is now live at https://fossil.craftdesign.group/<name>/. Cloudflare caches nothing from Fossil itself, but browsers keep the logo for an hour.

Copy-paste version

NAME=myrepo
DESC="What this repo does"
ICON=package      # see the icon list above
CAPS=ghoj         # public read; use jh for wiki-only
R=/var/fossil/repos/$NAME.fossil

fossil init $R
fossil user new dmestas dmestas $R
fossil config -R $R set project-name $NAME
fossil config -R $R set project-description "$DESC"
printf '%s\n%s\n%s\n' "$ICON" "$DESC" "$CAPS" > /var/fossil/repos/$NAME.meta
printf '# %s\n\n%s\n' "$NAME" "$DESC" | fossil wiki create index -mimetype text/x-markdown -R $R
fossil login-group join /var/fossil/repos/zit.fossil -R $R
python3 /var/fossil/skin/apply.py

Mirrors

Repos that live on GitHub (go-libfossil, edgesync) are imported with full history by /var/fossil/mirror/git-mirror.sh and refreshed hourly from cron. To add one:

/var/fossil/mirror/git-mirror.sh init <name> <git-url> "<description>"

Then do steps 2, 4 and 5 above. Don't commit to a mirrored repo on this server; changes go to GitHub and arrive on the next sync. The log is at /var/fossil/mirror/sync.log.

Where things live

Path	What
/var/fossil/repos/*.fossil	the repositories
/var/fossil/repos/*.meta	icon, description, public access
/var/fossil/skin/	apply.py, css.txt, header.txt, footer.txt, logo.png, icons/
/var/fossil/www/index.html	landing page; the repo grid between the REPO-GRID markers is generated
/var/fossil/mirror/	git mirror script, marks files, sync log

The skin and scripts are versioned in the fossil-skin repo. Edit there, then scp the files to the server and run apply.py.