I have been writing documentation for a project in markdown using RStudio, which provides a nice way of packaging it all as a static (html) website. I wanted to share this work with colleagues securely.
The documents exist within an RStudio project and are built to a folder containing static files. That folder is by default
_book, but I change this to
docs to make it easy to deploy as a github site if I wish1. Configuration management is a crucial element to proper productivity, not just in software but also in all walks of life where documentation is important. Because of this, I use github to store my work safely, should I lose a laptop or suffer some other first-world calamity. It’s one of the reasons I use markdown when writing: configuration management is well-suited to text-based documents because it is easy to track and manage changes.
Although I keep the source files on github, I haven’t published this project to github pages because it should not be publicly available: instead, I deploy to a VPS (Centos/Apache/Plesk), putting it all behind a login.
I set up a specific domain
static.cullaloe.net for this project, and secured it with an SSL certificate.
Clone the GitHub repository into a new folder somewhere behind the web-facing directory (i.e. not in httpdocs). In this example, both the repository and the local folder are called “foobar”:
$ git clone https://github.com/githubuser/foobar.git /var/www/vhosts/[domain]/foobar
It is not necessary to specify the target directory, you’ll get that as default. If you do, the new directory must be empty. It is not possible2 to selectively clone a github project: it’s all or nothing.
/var/www/vhosts/[domain]/foobar now contains all of the source files of the project.
You need to create a
.htpasswd file in the server somewhere, containing the username and password you wish to grant access to your files to:
$ /path/to/htpasswd -c /var/www/vhosts/[domain]/.htaccess user1
This prompts you for the password you wish to set for this user. Adding another user is the same command without the
You need to tell the Apache, using
Alias, where to find the files, and with
<Location>, control who can access files at the URL you are trying to protect. In the Plesk control panel, Apache & nginx Settings for static.cullaloe.net ···:
Alias /foobar /var/www/vhosts/[domain]/foobar/docs <Location /foobar> AuthType Basic AuthName "Restricted access" AuthUserFile /var/www/vhosts/[domain]/.htpasswd Require user user1 </Location>
I can easily continue to work on my project documentation, updating it from time to time for colleagues who are interested in seeing what I’m doing. I make (neurotic) use of github for configuration management and safekeeping of all my hard work anyway, so updating the site just requires
$ git pull from the repository folder on the web server. They can then view the documentation in a browser, or download a pdf or docx that is up-to-date with my current progress.