7.0 KiB
Guide on installing werc
Werc is the cms that runs in https://kill-9.xyz (and it 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/ 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/ /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
-
There's a new werc version available but it seems to have breaking changes so i'm sticking to this old version. ↩︎