aboutsummaryrefslogtreecommitdiffstats
path: root/man/blogc-git-receiver.1.ronn
diff options
context:
space:
mode:
Diffstat (limited to 'man/blogc-git-receiver.1.ronn')
-rw-r--r--man/blogc-git-receiver.1.ronn126
1 files changed, 126 insertions, 0 deletions
diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn
new file mode 100644
index 0000000..e26ed09
--- /dev/null
+++ b/man/blogc-git-receiver.1.ronn
@@ -0,0 +1,126 @@
+blogc-git-receiver(1) -- a simple login shell/git hook to deploy blogc websites
+===============================================================================
+
+## SYNOPSIS
+
+chsh -s $(command -v `blogc-git-receiver`) <user>
+
+## DESCRIPTION
+
+**blogc-git-receiver** provides a PaaS-like way to deploy blogc(1) websites.
+When used as a login shell, it will accept git payloads, creating bare repositories
+as needed, and installing a hook, that will take care of rebuilding the website each
+time someone push something to the `master` branch.
+
+The git repository must provide a `Makefile` (or a `GNUMakefile`), that should
+accept the `OUTPUT_DIR` variable, and install built files in the directory pointed
+by this variable.
+
+`blogc-git-receiver` is part of `blogc` project, but isn't tied to blogc(1). Any
+repository with `Makefile` that builds content and install it to `OUTPUT_DIR`
+should works with `blogc-git-receiver`.
+
+## SETUP
+
+After creating an user (`blogc` for the examples), change its shell to
+blogc-git-receiver(1):
+
+ # chsh -s $(command -v blogc-git-receiver) blogc
+
+Now add ssh keys to `/home/blogc/.ssh/authorized_keys`. Every key in
+`authorized_keys` will be allowed to push to the git repositories, and even
+create new ones.
+
+Also, make sure to install all the dependencies required by the websites,
+including a web server. `blogc-git-receiver` can't handle web server virtual hosts.
+
+To deploy a website (e.g. blogc example repository):
+
+ $ git clone https://github.com/blogc/blogc-example.git
+ $ cd blogc-example
+ $ git remote add blogc blogc@${SERVER_IP}:blogs/blogc-example.git
+ $ git push blogc master
+
+This will deploy the example to the server, creating a symlink to the built content
+in `/home/blogc/repos/blogs/blogc-example.git/htdocs`. This symlink should be used
+as the document root for the web server virtual host.
+
+### Setup with SELinux enabled (Fedora)
+
+Supposing the usage of nginx as webserver, running as the `nginx` user:
+
+ # dnf install -y nginx policycoreutils-python-utils
+ # useradd -m -s $(command -v blogc-git-receiver) blogc
+ # gpasswd -a nginx blogc
+ # chmod -R g+rx /home/blogc
+ # su -c "mkdir /home/blogc/{builds,repos}" -s /bin/sh blogc
+ # semanage fcontext -a -t httpd_sys_content_t "/home/blogc/(builds|repos)(/.*)?"
+ # restorecon -R -v /home/blogc
+ # systemctl restart nginx
+
+After running these commands, the machine is ready to be used.
+
+## REPOSITORY MIRRORING
+
+Users can rely on `blogc-git-receiver` to mirror repositories to a remote Git
+repository (e.g. a free Bitbucket private repository). This feature just requires
+adding a remote called `mirror` to the bare repository in the server. If such remote
+exists, `blogc-git-receiver` will `git push --mirror` to it.
+
+Please note that the `blogc` user must be able to push to the remote repository, and
+that any content manually pushed to the remote repository is overwritten by
+`blogc-git-receiver`.
+
+Some reasonable ways to allow the `blogc` user to push to the remote repository are:
+
+- Create a password-less SSH key. The key *must* be password-less, because the push
+ is automatic, and remote git hooks can't be interactive.
+- Create an oauth token in the hosting service (if it supports oauth authentication
+ in git, e.g. GitHub) and add it to the git URL.
+
+The mirroring feature wont't block a `git push`, it will just raise warnings. That
+means that if an error happens when mirroring the repository, the deploy will still
+succeed. Users should pay attention to the git hook logs, to avoid losing data
+due to repositories not being mirrored.
+
+To add the `mirror` remote:
+
+ # su -s /bin/bash - blogc
+ $ git remote add --mirror=push mirror $YOUR_GIT_MIRROR_URL
+
+### Caveats of repository mirroring with SSH
+
+The authentication must be done with a password-less SSH key created by the `blogc`
+user.
+
+As the `git push --mirror` call is automated, users must disable SSH strict host
+checking in SSH's `~/.ssh/config` file:
+
+ Host bitbucket.org
+ StrictHostKeyChecking no
+
+The example uses `bitbucket.org` as remote host, that should be changed if needed.
+
+To change this file, users must login with `/bin/bash` or any other "real" shell,
+as `root`:
+
+ # su -s /bin/bash - blogc
+
+## ENVIRONMENT VARIABLES
+
+`blogc-git-receiver` will export an environment variable called `BLOGC_GIT_RECEIVER`
+when calling `gmake` to build websites. This variable can be used to enable building
+of content that should only be built when running in production environment, for
+example.
+
+## BUGS
+
+Please report any issues to: <https://github.com/blogc/blogc>
+
+## AUTHOR
+
+Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
+
+## SEE ALSO
+
+blogc(1), git(7), chsh(1), su(1), make(1)