mirror of git://git.qorg11.net/kill9.git
221 lines
7.0 KiB
Markdown
221 lines
7.0 KiB
Markdown
# 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/](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/ /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.
|