# 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:

* a good HTTP server that supports fcgi (nginx in this case)
* Plan 9 utils

## 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/](9base) or
[https://9fans.github.io/plan9port/](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:

~~~{.bash .numberLines}
# 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:

~~~{.bash .numberlines}
# 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]

~~~{.bash .numberLines}
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:

~~~{.bash .numberLines}
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.

~~~{.bash .numberLines}
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:

~~~{.bash .numberLines}
#!/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`:

~~~{.bash .numberLines}
# 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

~~~{.conf .numberLines}

    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:

~~~{.bash .numberLines}
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](/themes). 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.
