Guide on installing werc

Werc is the cms that runs in https://kill-9.xyz (and its mirrors). It also powers popular niche sites like http://suckless.org and http://cat-v.org these being the original werc authors. It is very lightweight and doesn’t have any weird dependence like NodeJS, php or anything like that.

It is written in the, ehem, Plan 9 shell (rc), which means that, unless you’re running plan 9 (or 9front) in your server, you have to install the plan 9 utils to run werc.

This should work in any Linux distribution and BSD (I haven’t tried yet, if you have tried installing werc in BSD and that went succesfully, please tell us in #kill-9 in Rizon).

You can write the articles in any format, as long as it can be converted to HTML, but we use markdown here in kill-9.

The werc homepage is http://werc.cat-v.org

Requirements

werc is, for the discomfort of soydevs, a good piece of software that doesn’t require to have 2 HTTP servers at once, it simply runs in nginx using fcgiwrap, so you require:

Getting started

As stated above, werc is written in rc, the Plan 9 shell, and it depends on several Plan 9 commands, so you have to install a Plan 9 userspace in your machine. You can use any Plan 9 implementation such as http://tools.suckless.org/9base/ or https://9fans.github.io/plan9port/, because of the minimalism meme, we are going to use 9base.

If you are a sane person and use Debian as a sever, lucky you! it is in the repos by default, if you use something that doesn’t have 9base in its repos, you’ll have to compile it yourself, luckily it is suckless software so it’s easy to compile, but it will take a while because it also has to compile the Plan 9 build system.

So, to install the thing in debian, run:

# apt install 9base

When you install it, it shold be installed in /usr/lib/plan9, in the bin directory resides the rc binary, and we need it to be in somewhere accesible, like /bin/ so you’ll have to create a symlink, hardlink, copy the file, whatever, thing is that you run rc and it works:

# cp /usr/lib/plan9/rc /bin/

If you run rc and it changes the prompt, it works, now press C-d to exit the rc shell.

Getting werc

Cool! Now we have the Plan 9 userspace installed, now we have to get werc!

We are going to install werc in /var/www/werc but you can install it wherever, so just run mkdir /var/www/werc

and then get the tarball from http://werc.cat-v.org/download/werc-20170728.tgz 1

cd /var/www/werc
wget http://werc.cat-v.org/download/werc-20170728.tgz
tar -xzvf werc-20170728.tgz
mv werc/* .
rm -rfv werc # Only .hg directory is left.

Cool, now you have werc installed!

Now go to the sites directory and make a directory for your site:

cd sites
mkdir mysite.tld
cd mysite.tld
echo "Hello, werc!" > index.html
# Now, set up the website title and subtitle
mkdir _werc
echo -e "siteTitle='werc example'\nsiteSubTitle='considered harmful'" > config

Now you have the site, now you have to configure werc so it knows where to get the Plan 9 utils, the configuration file is in etc/initrc.

cd /var/www/werc
cd etc
$EDITOR initrc

Uncomment line 14 and change it to the installation of 9base, which should be /usr/lib/plan9 as state above.

You can also change the formatter from md2html.awk to something more powerful such as pandoc, so change that from md2html.awk to markdown.sh (This is only if you want to use pandoc as formatter).

Which means that you’ll have to write the markdown.sh script, these scripts are in bin/contrib, so create the markdown.sh file there with the following content:

#!/bin/sh

pandoc -s --highlight-style breezedark -t html

and give it chmod +x.

Web server configuration

Cool, we have configured werc, now we have to configure the webserver so it can serve werc, as state above, we are using nginx for this purpose, asuming you use debian and have a sites-enabled directory, put the following in /etc/nginx/sites-enabled/werc.conf, if you don’t have sites-enabled, just put it inside the http {} block inside nginx.conf.

Oh, and before, you have to install fcgiwrap:

# apt install fcgiwrap
# systemctl enable fcgiwrap
# systemctl start fcgiwrap

The socket should be placed in /var/run/fcgiwrap.socket

This configuration was copy-pasted from the werc documentation site


    server {
        listen       80;
        server_name  mysite.tld; # Replace with your domain name.

        #charset utf-8;

        #access_log  logs/host.access.log  main;

        location / {

        # FastCGI params, usually stored in fastcgi_params
        # and imported with a command like the following:
        #include        fastcgi_params;

        # Typical contents of fastcgi_params (inlined here):
        # You might have to repleace this with wherever you have your
        # fcgi socket
        fastcgi_pass unix:/var/run/fcgiwrap.socket;
        fastcgi_param  QUERY_STRING       $query_string;
        fastcgi_param  REQUEST_METHOD     $request_method;
        fastcgi_param  CONTENT_TYPE       $content_type;
        fastcgi_param  CONTENT_LENGTH     $content_length;

        #fastcgi_param  SCRIPT_FILENAME   /var/www/werc/bin/werc.rc;
        fastcgi_param  SCRIPT_NAME        /var/www/werc/bin/werc.rc;
        #fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;

        fastcgi_param  REQUEST_URI        $request_uri;
        fastcgi_param  DOCUMENT_URI       $document_uri;
        fastcgi_param  DOCUMENT_ROOT      $document_root;
        fastcgi_param  SERVER_PROTOCOL    $server_protocol;

        fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
        fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

        fastcgi_param  REMOTE_ADDR        $remote_addr;
        fastcgi_param  REMOTE_PORT        $remote_port;
        fastcgi_param  SERVER_ADDR        $server_addr;
        fastcgi_param  SERVER_PORT        $server_port;
        fastcgi_param  SERVER_NAME        $server_name;
        fastcgi_param  REMOTE_USER        $remote_user;

        #root   /var/www/werc/sites/$server_addr; # XXX This doesn't work, not sure why :(
        root /;
        #index  index.html index.htm;
        }

Then restart nginx:

systemctl restart nginx

And if everything’s working, if you go to http://mysite.tld werc should be working. Showing the “Hello, werc!” message we gave.

Now you can test that subdirectories and all are working, by creating new files and directories:

echo "# it wercs > otherthing.md"
mkdir "a_dir";
echo "# yup, it wercs" > a_dir/index.md

That’s all, werc is highly customizable, we have made some themes for werc you can find here. the css files are in pub/style


  1. There’s a new werc version available but it seems to have breaking changes so i’m sticking to this old version.↩︎