src/darcsit/README

    Darcsit: a wiki engine for Basilisk

    Darcsit is “inspired” from gitit from John Mac Farlane. I put “inspired” within quotes because “plagiarised” could be a better description! This concerns mostly the layout and CSS style files though. The engine itself (darcsit) is completely different. It is written in bash rather than Haskell to start with, but also uses the excellent pandoc, also from John.

    How to setup your own wiki

    Darcsit is designed to be usable on its own. It can be used for example to setup a (typically temporary) interactive website, that students in a course would use to write their own documentation and run their own Basilisk simulations, all through the web interface of the wiki.

    To do this you will need to have:

    • Administrative rights for an Apache web server,
    • Account creation privileges i.e. root access on the same server.

    Apache configuration

    The Apache server will need to have the MPM (Multi-Processing Module) enabled. This can be installed using:

    sudo apt install libapache2-mpm-itk

    See also this page.

    Since the Darcsit server is a bash script, CGI will need to be enabled, this can be done using

    sudo a2dismod cgid
sudo a2enmod cgi

    Note that MPM is not compatible with cgid so that cgid needs to be disabled (but not cgi).

    You will also need the mod_rewrite module i.e.

    sudo a2enmod rewrite

    Account setup

    Since the wiki will be able to write to disk (and also optionally run user-provided code), it is a good idea to run the server as a standard and different user from the other Apache servers (this is what the mpm-itk module does). We must first create this user, let’s call it darcsit.

    sudo adduser darcsit

    We then create an initial (empty) wiki directory using something like:

    su darcsit
cd ~darcsit
mkdir wiki
cd wiki
darcs init
mkdir static
cd static
ln -s $BASILISK/darcsit/static/css
ln -s $BASILISK/darcsit/static/js
ln -s $BASILISK/darcsit/static/img

    To be able to use codemirror instead of the default basic text editor, it needs to be installed in static/ using:

    cd ~darcsit/wiki/static/
wget https://codemirror.net/codemirror.zip
unzip codemirror.zip
rm codemirror.zip
mv codemirror-* codemirror

    To add support for “Basilisk C” syntax in codemirror, we need to apply a patch, like this:

    cd ~darcsit/wiki/static/
patch -p0 < $BASILISK/darcsit/codemirror.patch

    Note that the patch was made for version 5.46 of codemirror and may need to be adapted for later versions.

    Apache configuration file for the wiki

    We now need to setup the Apache configuration for the wiki. This can be done (as root) using:

    cp $BASILISK/darcsit/darcsit.conf /etc/apache2/sites-enabled/mywiki.conf

    The top part of miwiki.conf must then be edited to configure the wiki. The available options are commented in the file. Just follow the instructions there.

    You also need to make sure that eveything is setup so that you can generate local HTML pages.

    Once this is done use:

    /etc/init.d/apache2 reload

    to reload the configuration. Your wiki should now be fonctional, at the address you set in mywiki.conf.

    Running code from the wiki

    To run code from the wiki you first need to have access to a Basilisk server. You will need to allow the darcsit user to access the server i.e. you need to generate an SSH public key for this user and copy it in the .ssh/authorized_keys file on the server. Use something like:

    su darcsit
cd ~darcsit
ssh-keygen
scp ~/.ssh/id_rsa.pub basilisk.server:
ssh basilisk.server
etc..

    You then need to add the logins allowed to run code to the darcsit-runners file (or any other file you configured in mywiki.conf).

    Inline graphics

    Inline graphics are generated locally (i.e. by the wiki server). To improve security, since this involves running user-provided commands, this is done using the basilisk-untrusted user through sudo. So we need to give darcsit the right to sudo to basilisk-untrusted. This can be done using:

    sudo -s
echo "darcsit ALL=(basilisk-untrusted) NOPASSWD: ALL" >> /etc/sudoers.d/basilisk

    Changing the layout

    The default layout, styles, images etc… are defined in the static/ directory and in $BASILISK/darcsit/templates. To change it, you will need to

    1. Change wiki/static/img/logo.png. This involves replacing the symbolic link to img/ with a copy of the directory.
    2. Make a new templates/ directory i.e. mkdir wiki/static/templates.
    3. Copy the templates you need to modify e.g. cp $BASILISK/darcsit/templates/page.st wiki/static/templates/.
    4. Edit page.st (and other templates e.g. sitenav.st if necessary).
    5. Regenerate the page template (page.static), using:
    cd wiki/static/templates/
make -f $BASILISK/darcsit/templates/Makefile

    Note that you may need to remove old .html files to force regeneration of these pages using the new template. This can be done using something like:

    cd wiki
rm -f `find . -name '*.html'`

    Be careful if you have your own ’*.html’ files for some reason.

    Troubleshooting

    • If “history” or “Recent activity” do not work, make sure that the version of darcs on the server is less than 2.8.5.
    • If “changes” does not work, this may be due to your version of awk: make sure (using awk --version) that you are using gawk (and not mawk for example).