1 files changed, 77 insertions, 0 deletions
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..0a29cde
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,77 @@
+# Wormhole
+
+Enables you to send messages from mastodon into a wormhole to have it go through time and space and appear in a new galaxy!
+
+In this new galaxy, you can see what other people have shared and subscribe to it's RSS feed to receive updates. What a great way to share links with friends!
+
+## Motivation
+
+I am part of a group of researchers / decentralization enthusiasts, and we want to have a way to share links that we found interesting. Along with that, we'd also like to be able to discuss and comment on those. Initially I built a boring link sharing server where you logged in and shared things. Instead, more interesting would be to send everything into a wormhole, where the shared links pop up on the other side. From there, people can follow content updates by either going into the website or subscribing to an RSS feed.
+
+I built it in OCaml because it is by far the most underrated programming language on the planet and the web framework Dream is a BEAST in terms of productivity. Hyper fast compilation speed + great performance + productive + safe + lots of industry use.
+
+## Prerequisites
+
+You'll need `libev` and `openssl`.
+
+## Running
+
+```
+dune exec --watch --root . ./server.exe
+```
+
+## Build
+
+```
+opam build
+opam exec -- dune build
+```
+
+## Hosting
+
+You can make use of the dockerfile to host your wormhole, personally I host it on a 4gb VPC on Hetzner for 8$ a month using Dokku.
+
+### Hosting with dokku
+
+Follow the install instructions from [dokku](https://dokku.com/), attach your dokku instance to a domain, then create a new app:
+
+```
+root@server$ dokku apps:create my-wormhole
+```
+
+Now, clone this repo and add a new remote, then push it to create the app
+
+```
+you@comp$ git remote add dokku dokku@your-dokku-domain.com
+you@comp$ git push dokku master
+```
+
+This will set up the instance. I had little success with this on a 2gb VPC, so do avoid that.
+
+Once up, let's setup SSL for it to work:
+
+```
+root@server$ dokku plugin:install https://github.com/dokku/dokku-letsencrypt
+root@server$ dokku letsencrypt:set my-wormhole email your@email.tld
+root@server$ dokku letsencrypt:enable my-wormhole
+```
+
+Now it should be possible to find your wormhole in Mastodon! Look for @wormhole@my-wormhole.your-dokku-domain.com.
+
+## Development
+
+Good documentation:
+
+- [Yojson](https://github.com/janestreet/ppx_yojson_conv)
+
+### Testing
+
+You can install `hurl` do to integration tests. For example:
+
+```
+hurl http/inbox.hurl
+```
+
+## Contributing
+
+Send patches to marc@mccd.space. Never sent email patches before? Check out [this tutorial](https://git-send-email.io/). Let us move to a more decentralized ecosystem for open source development!