Skip to content
Snippets Groups Projects

WebsiteProposalClv

Last edited by Alexander Færøy

This proposal is a contribution to the Website wiki.

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.

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 markdown text.

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

Platform layer

As mentioned earlier, we need to set-up a git repository in which we will have our static website generator and some git submodules to host content and templates. For example, if we wanted to use Jekyll we would need to install jekyll and ruby packages in our favorite package manager. 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 as: there is a main server where public keys of authorized users are stored, and each user having his own private key and then pushing/pulling to the main server by connecting through a ssh user called git. The best example of this workflow 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@[github.com:user/repo.git github:user/repo.git] .

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

repo tor-website-layouts
   RW+     = admin1 designer1

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 previously generate a ssh key pair and send his public key to admin1, who would receive that key and store it on the server with the name editor1.pub. 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, content and layouts) _are empty, so it's necessary to clone them and add something to them (for now I will show examples of main and articles, but the same applies for layouts). First, we clone the tor-website-main repository (with user admin1) and copy a fresh jekyll website structure inside of it. Jekyll has a folder called _posts where its store the website posts 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 the dummy article:

---
layout: post
title:  "New Tor website"
date:   2015-09-26 21:51:05
categories: website tor
---
### Some header

This is a dummy article.

The next step is to add the tor-website-articles repository inside the main repository as a git submodule and rename it as _posts folder.

# git submodule add location destination
[admin1@somepc tor-website-main]$ git submodule add https://github.com/user/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 tor-website-main has a full working Jekyll folder structure! We can generate (build) the static HTML output or we can preview the changes with a built-in server provided by jekyll.

# the static files will be generated on the folder _site, but that can be customized
[admin1@somepc tor-website-main]$ jekyll build --destination /path/to/safe/html/build
# or serve the website and preview the site
[admin1@somepc tor-website-main]$ jekyll serve

From now on, everytime editor1 adds/changes a new article in tor-website-articles, admin1 will have to pull those changes from tor-website-articles into tor-website-main and then commit and push.

[editor1@otherpc tor-website-articles]$ git add 2015-09-27-tor-0-2-7-3-rc.md
[editor1@otherpc tor-website-articles]$ git commit -m "Tor 0.2.7.3-rc released"
[editor1@otherpc tor-website-articles]$ git push

[admin1@somepc tor-website-main]$ cd _posts
[admin1@somepc _posts]$ git pull origin master
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
From server:tor-website-articles
 * branch            master     -> FETCH_HEAD
   48f507d..d4a0193  master     -> origin/master
Updating 48f507d..d4a0193
Fast-forward
 2015-09-27-tor-0-2-7-3-rc.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 2015-09-27-tor-0-2-7-3-rc.md

[admin1@somepc _posts]$ cd ..
[admin1@somepc tor-website-main]$ git add _posts
[admin1@somepc tor-website-main]$ git commit -m "New post added"
[admin1@somepc tor-website-main]$ git push

There are a couple of interesting things to notice:

  • There is an initial configuration process where the sysadmin has to receive public keys and associate them with users and repos.
  • Everything that admin1 did was on his machine... No need to login to the server.
  • 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 (configure tor-website-layouts repo as _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.

Note 1 (live example): I have a live working example on my github account:

Note 2 (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 this users have to do is clone the corresponding repositories, create a file following Markdown format and learn just a few things about YAML Front Matter (if we use Jekyll). YAML Front Matter allows to use permalinks, categories, tags, etc. or even define custom variables (such as lang).

**Note: **there is a real nice open source text editor called Atom which has a plugin for writing in Markdown with live preview.

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 with HTML templates and pushing changes to their respective repository (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.

Summary

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.

Comments

    Please register or sign in to add a comment.