Version 3 (modified by clv, 5 years ago) (diff)

Content, presentation and summary

Proposal Overview

The key aspects of this proposal are:

  • Setup a secure and reliable platform for managing Tor Website.
  • Design a role-based workflow in order to foster collaborative work on the website.
  • Update current website to use new technologies/tools.

For this purposes the proposal features a multi-layer design consisting of: Platform, Content, Presentation.

The Platform layer consists of a Git-based setup, on top of which there will be Gitolite for authorizing users and Git submodules to separate repositories for each of the roles that the website will need, namely: admins, editors, designers. Aditionally, the Platform will have a static website generator (Jekyll, Pelican, Hugo, etc.) to build the website on the git repositories.

The Content layer is just the content: website news, tutorials, documentation, etc. but in a content-oriented format, namely Markdown. People working on the content layer will be focused on writing news, documentation, etc. and not worrying about the platform or the design, just plain text.

The Presentation layer consists in delivering content to the users in a nice way through the website, mobile app, ebook, etc. People working on the presentation layer will have to work with HTML templates.

Platform layer

As mentioned early, we need to set-up a Git repository in which we will have our static website generator and some Git submodules to host the content and templates. For example, if we wanted to use Jekyll we would need to install jekyll and ruby packages. Then, we need to install and configure Gitolite. (I'm not sure how Tor repos and permissions are being handled right now, so that's why I'm assuming we start from the bottom installing everything). Gitolite workflow can be summarized to: having public keys for every user on a server and each user having his own private key and then pushing/pulling to the server using the git user. The best example is Github: you generate a key pair, upload your public key to the server and the you can clone repos via ssh: git clone git@…:user/repo.git . In addition, there is a configuration file that Gitolite uses to give users permissions to specific repositories. For example, we could have the following configuration file:

repo tor-website-main
   RW+     = admin1

repo tor-website-articles
   RW+     = admin1 editor1

admin1 has access to both repositories, while editor1 has access to tor-website-articles only. It's important to notice that, as I mentioned before, editor1 would need to generate a ssh key pair and send his public key to the website admin, who would receive that key and store it on the server with the name Then, editor1 will be allowed to use his private key to push/clone/pull to the server (to the allowed repositories).

The previous repositories (main and articles) are empty, so It's necessary to clone them and add something to them. First, we clone the tor-website-main repository and copy a fresh Jekyll website structure inside of it. Jekyll has a folder called _posts where its store the website content in markdown format. We will delete that folder as we want to delegate the content to another repository.

[admin1@somepc ~]$ git clone git@server:tor-website-main
[admin1@somepc ~]$ jekyll new tor-website-main
[admin1@somepc ~]$ cd tor-website-main
[admin1@somepc tor-website-main]$ rm -rf _posts
[admin1@somepc tor-website-main]$ git add *
[admin1@somepc tor-website-main]$ git commit -m "Fresh Jekyll structure added"
[admin1@somepc tor-website-main]$ git push origin master

Now we clone the tor-website-articles repository (with user editor1) and add a dummy article (in markdown).

[editor1@otherpc ~]$ git clone git@server:tor-website-articles
[editor1@otherpc ~]$ cd tor-website-articles
[editor1@otherpc tor-website-articles]$ nano 2015-09-26-new-website.markdown
[editor1@otherpc tor-website-articles]$ git add 2015-09-26-new-website.markdown
[editor1@otherpc tor-website-articles]$ git commit -m "First article"
[editor1@otherpc tor-website-articles]$ git push origin master

Here is the content of a dummy article:

layout: post
title:  "New Tor website"
date:   2015-09-26 21:51:05
categories: website tor
This is a dummy article.

Jekyll offers powerful support for code snippets:

{% highlight ruby %}
def print_hi(name)
  puts "Hi, #{name}"
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}

The next step is to add the tor-website-articles repository inside the main repository as if it was the _posts folder.

# git submodule add location destination
[admin1@somepc tor-website-main]$ git submodule add git@server:tor-website-articles _posts
[admin1@somepc tor-website-main]$ git submodule init
[admin1@somepc tor-website-main]$ cd _posts
[admin1@somepc tor-website-main]$ git pull origin master
# With the previous pull, the main repo is updated and a commit has to be done. 
[admin1@somepc tor-website-main]$ cd ..
[admin1@somepc tor-website-main]$ git commit -m "Added articles submodule"
[admin1@somepc tor-website-main]$ git push origin master

So now the tor-website-main has a full working Jekyll folder structure and we can run jekyll in order to generate and serve the static HTML files.

# the static files will be generated on the folder _site, but that can be customized
[admin1@somepc tor-website-main]$ jekyll build
# serve the website in background, by default
[admin1@somepc tor-website-main]$ jekyll serve -B

There are a couple of interesting things to notice:

  • Everything that admin1 did was on his machine... No need to login to the server (of course, someone had to configure the server previous to that).
  • editor1 doesn't have access to the jekyll folder structure, just the posts folder. In other words, editor1 just focus on writing posts. The same can be applied to designer1 who would modify website templates (_layouts folder).
  • admin1 needs to pull the changes from git submodules.
  • The proposal is not dependent on jekyll. This same approach can be used with otherstatic website generators such as Pelican, Hugo, etc.

A note on security: we could use signed commits to improve security on critical repositories.

Finally, for this "Platform" layer we would need at least two people: someone with access to the git server who will be in charge of maintaining the server up-to-date, configuring gitolite, add new users, add repositories, etc. In other words, a sysadmin. Another person to pull (and if needed review) all of the pull requests from git submodules.

Content Layer

As shown earlier in the Platform layer, we can have a role for editor1 who will be contributing with news/sections/manuals, etc. We could even have several roles: editor, translator, news-editor. All they have to do is create a file following the Markdown format and learn just a few things about YAML Front Matter (if we use Jekyll). YAML Front Matter allow us to use permalinks, categories, tags, etc. or even define custom variables (such as lang).

Note:  there is a real nice text editor for Linux called Atom which has a plugin for writing in Markdown with live rendering of the output.

Presentation Layer

The Presentation layer is about to delivering content to users, and this can be done in different ways. One way to do it is to take the Markdown files made by content-creators (writers, translators, etc.) and deliver that content to the users through a website. Other ways of delivering the same content could be with a mobile app, by downloading an ebook file, etc. In the case of a website we can have a team of web designers working on HTML templates and pushing changes to their respective repository (something like tor-website-layouts) without interfering with the work of content-creators or sysadmins. Furthermore, in the future we could have both a team of web designers and ebook editors (writing an ebook of Tor tutorials) working on top of the same content but with independent workflows.


This proposal presents a way to setup a secure and reliable system with role-based collaborative workflow for the Tor website, which I think makes it easier for non-tech people to collaborate to the Tor website on their specific areas of interest: news, tutorials, HTML layouts, etc.