Repository files navigation

Canopy is an attempt at writting a blog-engine based on Git usingMirageOS.

The goal is to provide a simple blog platform that only requires you to provide a Git remote URL and respecting some architecture rules within the said repository.

Canopy is written in OCaml using MirageOS andIrmin. It is running on both Unix and Xen.

Canopy has TLS support, you have to first create your TLS private key and get asigned certificate (usingcertifyand/orlet's encrypt - sorry, no let's encryptclient in OCaml yet).

Put your unencrypted private key intotls/server.key, and your fullcertificate chain (starting with the server certificate, then the intermediateCAs, no need to include the root CA) intotls/server.pem before runningmirage configure (which will embed them as OCaml code into the binary).

You can configure Canopy with--tls=<port> to run it as HTTPSservice. Canopy will then respond to HTTP requests with amovedpermanently redirection tothe HTTPS URL. Also, the HTTPS service includes astrict transportsecurity HTTPheader (containingmax-age=31536000).

You will need at leastOCaml 4.07.1,opam 2.0 andmirage 3.7.5 before starting. To setup a mirage environment, please refer tothe mirage website.

Checkout Canopy repository, then go inside:

# Configure the mirage application, compile assetsmirage configure -t unix# Get dependenciesmake depend# Compile Canopymake# Run it./canopy

Note: if you run Canopy with a grsec kernel you might have to relaxmemory-mapping restrictions (i.e.:paxctl -cm canopy) and load thetunmodule.

A server will be launched using the specified URL as the git remote,Index as the default page rendered on the blog (it must exist within the repository) and8080 is the listening port.You can see more options by running./canopy --help.

To prepare your own data repository, you have to usenpm,less-css andbrowserify if you want to compile and retrieve everything related to the blog-styling. Themirage configure step takes care of fetching and recompiling all assets. If none of the mentioned programs were to be found, the configure step will use the tarball found in theassets directory, containing already compiled assets.

# OR start with git clone git://github.com/Engil/__blog.git ;)mkdir canopy-datacd canopy-datagit init .# Populate data using npm, browserify, etc.if [ -x `which npm` ] ; then  ./populate.sh /tmp/dataelse  # OR use pregenerated tarball  cd /tmp/data && tar xf assets/assets_generated.tar.gz  cd /tmp/data && mv disk/static .fi;git add static# Generate a UUID for the Atom feeduuidtrip -r > .config/uuid# Add blog name (defaults to "Canopy")echo "My blog" > .config/blog_namegit add .configgit commit -m initial# configure git remote and pushgit remote add origin git@github.com/me/__blog.gitgit push origin master

You can run Canopy with your own data repository:

./canopy -r git://github.com/me/__blog.git

You can use git branches for drafting changes:./canopy -r git://github.com/me/__blog.git#dev.

If you want to build for xen, there's a couple of packages that need to beinstalled from specific branches.

opam pin add dolog'https://github.com/UnixJunkie/dolog.git#no_unix'opam pin add bin_prot'https://github.com/hannesm/bin_prot.git#113.33.00+xen'

You can either build with support for DHCP or static ip, just specifying it ascommand line arguments, for instance:

mirage configure --xen --dhcpfalse --net direct --ip 10.0.0.2 --netmask 255.255.255.0 --gateways 10.0.0.1make

Make sure to havebr0 set up for this. For example, I did:

# provide ip forwardingecho'net.ipv4.ip_forward=1'>> /etc/sysctl.confsysctl -p /etc/sysctl.confiptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE# create a new bridgebrctl addbr br0ip addr dev br0 add 10.0.0.1/24ip linkset br0 up

Finally you can run your unikernel!

xl create -c canopy.xl

To keep your Canopy content updated, you need to tell your instance that new content is available on the git remote, then it will just pull the changes and will serve the new content.

To do that, Canopy use a simple URL path that you can set into Canopy_config.ml (hook_push_path).

Using Github, setting up this hook is pretty simple: just add a push webhook targeting your URL + your hook path.For example, by default this hook path ispush, so the resulting URL ishttp://yourdomain/push.

If you are not using Github, you can just find a way (post-commit-hooks, for example) to run a HTTP request to this URL.

Canopy will require you to provide a Git remote uri. Once started, it will clone in-memory the repository content and serve the content in a more or less organized way.

Each file at the root of the repository is considered a standalone page, more like the usual « About » or « Contact » pages. They will have their own entries in the navigation menu.

Each directories will contains more pages, but that will be classified under a category decided by the name of the said directory.For example, aposts/hello-word.md file will be a new blog post under thePosts category.You can use it to emulate some sort of tag, like for example having anOCaml directory regrouping all you writing in everyone's favorite language. :-)

Static assets (not processed) can be added into "static" subdir, configuration values below ".config".

The file syntax of articles is just plain markdown, everything should be supported out-the-box (depending on theocaml-omd markdown implementation), with a little bit of extra informations absolutely needed at the top of each files.

---title: A blog entryauthor: Meauthor_url: http://www.an_optional_link_that_wraps_the_author.comabstract: A simple line telling what this article is all about, will be displayed in listing pages. (optional)---article content

If you don't respect this syntax, then the article won't show up in the resulting website.

You can also put some MathJax inside articles, Mathjax is activated if you pass the --mathjax parameter at startup.