aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorqorg11 <qorg@vxempire.xyz>2021-12-24 14:00:13 +0100
committerqorg11 <qorg@vxempire.xyz>2021-12-24 14:01:20 +0100
commit7418e3a947ac2d9f7c2c99089218c8fcfa24c642 (patch)
tree4703ca952eed0730bb89b321ca31f8afc708077b
parent28b424a967a86213f496c2c77f3933aa8d6dbc0c (diff)
downloadkill9-7418e3a947ac2d9f7c2c99089218c8fcfa24c642.tar.gz
kill9-7418e3a947ac2d9f7c2c99089218c8fcfa24c642.zip
Added a werc installation guide.
-rw-r--r--guides/werc_installation.md220
1 files changed, 220 insertions, 0 deletions
diff --git a/guides/werc_installation.md b/guides/werc_installation.md
new file mode 100644
index 0000000..85ec47b
--- /dev/null
+++ b/guides/werc_installation.md
@@ -0,0 +1,220 @@
+# 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
+https://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.