|
|
|
This proposal is a contribution to the [https://trac.torproject.org/projects/tor/wiki/Website 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 [https://git-scm.com/docs/git-submodule 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 [http://gitolite.com/gitolite/install.html 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.
|
|
|
|
|
|
|
|
[[BR]]'''Note 1 (live example):''' I have a live working example on my github account:
|
|
|
|
|
|
|
|
* [https://github.com/leivaburto/tor-website-main tor-website-main] has the jekyll folder structure with _posts and _layouts as git submodules.
|
|
|
|
* [https://github.com/leivaburto/tor-website-articles tor-website-articles] has the posts in Markdown format.
|
|
|
|
* [https://github.com/leivaburto/tor-website-layouts tor-website-layouts] has the HTML layouts.
|
|
|
|
* https://leivaburto.github.io/tor-website-main/ is the live URL.
|
|
|
|
* Github automatically builds static HTML sites from repos that have jekyll folder structure (like tor-website-main). In the case of a custom server that doesn't do that, there will be necessary to build the static HTML site on a different repo. I added an example "build repo" in [https://github.com/leivaburto/tor-website-html tor-website-html] which has nothing but static HTML. The live ouput is in: https://leivaburto.github.io/tor-website-html/ .
|
|
|
|
* The [https://github.com/leivaburto/tor-website-articles/commits/master articles commit log] shows how is the workflow for content-creators. Very straightforward.
|
|
|
|
|
|
|
|
'''Note 2 (security):''' we could use [https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work 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 [http://jekyllrb.com/docs/frontmatter/ 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 [https://atom.io/ Atom] which has a [https://atom.io/packages/markdown-preview 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. |
|
|
|
\ No newline at end of file |