diff options
Diffstat (limited to 'man/blogc-git-receiver.1.ronn')
| -rw-r--r-- | man/blogc-git-receiver.1.ronn | 126 |
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 <<rafael@rafaelmartins.eng.br>> + +## SEE ALSO + +blogc(1), git(7), chsh(1), su(1), make(1) |