diff options
Diffstat (limited to 'man/blogc-git-receiver.1.ronn')
| -rw-r--r-- | man/blogc-git-receiver.1.ronn | 112 |
1 files changed, 21 insertions, 91 deletions
diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn index 3aac9f2..dc35621 100644 --- a/man/blogc-git-receiver.1.ronn +++ b/man/blogc-git-receiver.1.ronn @@ -12,13 +12,13 @@ When used as a login shell, it will accept git payloads, creating bare repositor 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 blogcfile(5) (if blogc-make(1) is installed), or -a `Makefile` (or a `GNUMakefile`) that should accept the `OUTPUT_DIR` variable, and -install built files into the directory pointed out by this variable. +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) or -blogc-make(1). Any repository with `Makefile` that builds content and install it to -`OUTPUT_DIR` should work with `blogc-git-receiver`. +`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 @@ -29,12 +29,7 @@ blogc-git-receiver(1): 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. It is also possible to add `blogc-git-receiver` as a command in -the `authorized_keys` file for each key, but this setup is slightly more tricky, -as you may leak shell access to an user by mystake, if you forget to add the command -to a key that should not have shell access. Only use this method if you don't have -another option (e.g. in shared hosting environments that only provide one shell -account), or if you know exactly what you are doing. +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. @@ -48,27 +43,7 @@ To deploy a website (e.g. blogc example repository): 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. If this symlink can't be -readed by your webserver for some reason, you can create it in some other directory -by adding the full symlink path to the ~/blogc-git-receiver.ini configuration file: - - $ $EDITOR ~/blogc-git-receiver.ini - [repo:blogs/blogc-example.git] - symlink=/path/to/my/symlink - -Do not duplicate the section if it already exists, just append the symlink path to -it. - -### Rebuild last successful build - -If for some reason you want to rebuild the last successful build of a given website, -you can run its `pre-receive` hook manually in the server: - - # su -s /bin/sh - blogc - $ cd ~/repos/blogs/blogc-example.git - $ ./hooks/pre-receive - -This should re-run the last build as if it was pushed to git. +as the document root for the web server virtual host. ### Setup with SELinux enabled (Fedora) @@ -88,7 +63,9 @@ 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). +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 @@ -106,29 +83,14 @@ means that if an error happens when mirroring the repository, the deploy will st succeed. Users should pay attention to the git hook logs, to avoid losing data due to repositories not being mirrored. -This feature just requires adding a remote called `mirror` to the bare repository -in the server, or creating a configuration file (~/blogc-git-receiver.ini), that is -a simple INI-style file where each repository is represented by a section and the -value of the `mirror` variable is the URL that should be used to push. - -Edit configuration file (recommended, do not duplicate the section if it already -exists, just append the mirror to it): - - # su -s /bin/sh - blogc - $ $EDITOR ~/blogc-git-receiver.ini - [repo:myblog.git] - mirror=$YOUR_GIT_MIRROR_URL - -Or to add the `mirror` remote: +To add the `mirror` remote: - # su -s /bin/sh - blogc + # su -s /bin/bash - blogc $ cd repos $ git init --bare myblog.git # if not created yet $ cd myblog.git $ git remote add --mirror=push mirror $YOUR_GIT_MIRROR_URL -Both examples assume that your repository is named `myblog.git`. - ### Caveats of repository mirroring with SSH The authentication must be done with a password-less SSH key created by the `blogc` @@ -142,49 +104,17 @@ checking in SSH's `~/.ssh/config` file: The example uses `bitbucket.org` as remote host, that should be changed if needed. -To change this file, users must login with `/bin/sh` or any other "real" shell, +To change this file, users must login with `/bin/bash` or any other "real" shell, as `root`: - # su -s /bin/sh - blogc - -### Push to mirror manually - -If for some reason you want to push the repository of a given website to remote -mirror, you can run its `post-receive` hook manually in the server: - - # su -s /bin/sh - blogc - $ cd ~/repos/blogs/blogc-example.git - $ ./hooks/post-receive - -WARNING: If you push manually and your server's repository is empty, you'll clean -your mirror repository. - -## ENVIRONMENT - -The following variables can be set in the SSH Server (usually in `~/.ssh/environment`) -to change `blogc-git-receiver` behaviour: - - * `BLOGC_GIT_RECEIVER_BASE_DIR`: - Path to the base directory that should be used by `blogc-git-receiver`. Defaults - to user's home directory. Useful for shared hosting environments that only provide - one shell user. - * `BLOGC_GIT_RECEIVER_BUILDS_DIR`: - Path to the directory that should be used to store the blogc builds. Defaults - to `$BLOGC_GIT_RECEIVER_BASE_DIR/builds`. This directory must be readable by - your webserver. This variable is useful to keep your git repositories unreadable, - while letting your webserver access the built files. In this case, users need to - also define custom symlinks for every repository in - `$BLOGC_GIT_RECEIVER_BASE_DIR/blogc-git-receiver.ini`, because the default - `htdocs` symlink inside the git repositories won't be acessible by the webserver. + # su -s /bin/bash - blogc -The following variable is exported by `blogc-git-receiver` when building websites -with make(1): +## ENVIRONMENT VARIABLES - * `BLOGC_GIT_RECEIVER=1`: - This variable can be used to enable building of content that should only be - built when running in production environment, for example. This variable will - not be exported when using blogc-make(1), whose builds are always considered to - be "production" (blogc-make(1) is never called with `-D`). +`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 @@ -196,4 +126,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc(1), git(1), git-shell(1), chsh(1), su(1), make(1) +blogc(1), git(7), chsh(1), su(1), make(1) |