Skip to content

A peer-to-peer stack for code collaboration

Add notes about packaging

Thomas Scholtes9d51101efeea
diff --git a/notes/2018-01-22-packaging.md b/notes/2018-01-22-packaging.md
new file mode 100644
index 0000000..84a1a26
--- /dev/null
+++ b/notes/2018-01-22-packaging.md
@@ -0,0 +1,131 @@
+Packaging
+=========
+
+This documents explains how we want to package and distribute Radicle.
+
+We will create packages for Brew, Debian, Pacman, and (possibly Nix). This
+packages will be made available through Github Releases.
+
+Haskell binaries will be statically linked with `-O2` optimization.
+
+Files to package
+----------------
+
+The Radicle package contains the `rad` entry command, the `rad-xxx` subcommands
+and Radicle source files.
+
+The `rad` command will be installed into a `PATH` directory. The subcommands and
+Radicle source files are installed into distribution specific directories. For
+Debian and Pacman this is `/usr/lib/radicle/modules` for the Radicle source
+files and `/usr/lib/radicle/bin` for the subcommands.
+
+Locating packaged files
+-----------------------
+
+The binaries distributed with the package need to locate files on the system the
+package is installed on.
+
+* The `rad` entry command locates all installed subcommands to be able to list
+ them and dispatch to them.
+* Radicle apps (implemented as subcommands) need to locate Radicle source files.
+* If Radicle app frontends that are written in radicle the interpreter also needs
+ to locate Radicle source files to be able to import them.
+
+In addition to installed packages the location mechanism needs to work for
+development builds (`stack build`), local tests, and CI tests.
+
+To implement file location of subcommands we are going to use Cabal’s
+[`Paths_radicle`][cabal-paths] module. `getBinDir` will return the folder
+containing all subcommands.
+
+File location for Radicle source files will be implemented by reading the
+`RADPATH` environment variable
+
+For local development and testing this mechanisms work out of the box. For
+packages the `rad` command will be a script with the following content.
+
+```
+#!/bin/sh
+radicle_bin=/usr/lib/radicle/bin
+RADPATH=/usr/lib/radicle/modules
+exec $radicle_bin/rad "@$"
+```
+
+Setting `radicle_bin` will determine the return value of `getBinDir`. Setting
+`RADPATH` will enable other commands to pick up Radicle source files.
+
+### Configuring the prefix at compile time
+
+If the project is built with Cabal we do not need to set the `radicle_bin`
+environment variable to change the output of `getBinDir`. We can use the
+`--bindir` option for `cabal configure`.
+
+Stack [does not support the `--bindir` option][stack-prefix-issue] so we have to
+work around by setting the corresponding environment variable.
+
+For the first iteration we will use a stack based build because of the
+work involved in building the project with cabal. (Defining package constraints
+identical to Stackage LTS, publishing Git dependencies, additional CI build
+scripts). We will use a Cabal based build in the future.
+
+[cabal-paths]: https://cabal.readthedocs.io/en/latest/developing-packages.html#accessing-data-files-from-package-code
+[stack-prefix-issue]: https://github.com/commercialhaskell/stack/issues/848
+
+Dependencies
+------------
+
+Radicle depends on the IPFS daemon. Packages must either register the IPFS
+daemon as a dependency or distribute the `ipfs` binary with them.
+
+Services
+--------
+
+For Radicle to work two services need to be running: the Radicle daemon and the
+IPFS daemon. For Debian in Pacman we will provide a Systemd Unit file for the
+Radicle daemon as well as installation instructions that include extra steps to
+enable the Radicle daemon service.
+
+The Radicle daemon Systemd Unit has a dependency on the IPFS Systemd Unit. If we
+distribute IPFS with the package we also need to add a Systemd Unit file for
+IPFS.
+
+For Brew on MacOS we will need to provide `plist` files for the services so they
+can be used with launchd.
+
+Continuous Delivery
+-------------------
+
+Packages will be released using a release pipeline in CI. The release pipeline
+will build the packages, create a Github release with the appropriate name and
+description, and attach the packages to the Github release. The release pipeline
+will be triggered by Git tags.
+
+To build Brew packages we will need to run the build pipeline on MacOS. Google
+Cloud Build does not support MacOS but Travis and Circle do.
+
+Release pipeline
+----------------
+
+This is how the release pipeline would look for a Debian package. For a Pacman
+package only minor modifications would need to be made.
+
+1. `stack build -- --flag radicle:release`. The flag disables some targets,
+ enforces static linking and `-O3`.
+2. Move all binaries built with stack to `$DEST/usr/lib/radicle/bin`
+3. Move all Radicle sources files to `$DEST/usr/lib/radicle/modules`
+4. Create `$DEST/usr/bin/rad` wrapper script as mentioned above.
+5. Create a `deb` package using [`fpm`][fpm]. `fpm` takes the Systemd file as a CLI option.
+6. Upload the `deb` file to Github releases
+
+[fpm]: https://github.com/jordansissel/fpm
+
+Signing release artifacts
+-------------------------
+
+We should sign all the release artifacts that we provide. How to accomplish that
+is still an open question.
+
+* If we don’t build on our own machines we effectively trust the CI service
+* We can add signatures to Github release later. We could download release
+ artifacts and sign them locally. CI could provide checksums for additional
+ security.