# `hackage-repo-tool`: Manage secure file-based package repositories **Please refer to the [package description](https://hackage.haskell.org/package/hackage-repo-tool#description) for an overview of `hackage-repo-tool`, TUF and `hackage-security`.** ## Setting up a secure file-based repo A file-based repository (as opposed to one running the actual [Hackage software](https://hackage.haskell.org/package/hackage-server)) is much easier to set up and will suffice for many purposes. Note that such a local file-based package repository can be turned into a remotely accessible secure package repository by any HTTP server supporting static file serving such as Nginx or Apache httpd. 1. Create a directory `~/my-secure-repo` containing a single subdirectory `~/my-secure-repo/package`. Put whatever packages you want to make available from your repo in this subdirectory. At this point your repository might look like ~/my-secure-repo/package/basic-sop-0.1.0.5.tar.gz ~/my-secure-repo/package/generics-sop-0.1.1.1.tar.gz ~/my-secure-repo/package/generics-sop-0.1.1.2.tar.gz ~/my-secure-repo/package/json-sop-0.1.0.4.tar.gz ~/my-secure-repo/package/lens-sop-0.1.0.2.tar.gz ~/my-secure-repo/package/pretty-sop-0.1.0.1.tar.gz ~/my-secure-repo/package/HsYAML-0.2.1.0.tar.gz *(Due to [#174](https://github.com/haskell/hackage-security/issues/174) this folder must contain at least one package tarball or `hackage-repo-tool` will fail in non-obvious ways)* Note the flat directory structure: different packages and different versions of those packages all live in the one directory. 2. Create public and private keys: # hackage-repo-tool create-keys \ --keys ~/my-private-keys This will create a directory structure such as ~/my-private-keys/mirrors/id01.private ~/my-private-keys/mirrors/.. ~/my-private-keys/root/id04.private ~/my-private-keys/root/.. ~/my-private-keys/snapshot/id07.private ~/my-private-keys/target/id08.private ~/my-private-keys/target/.. ~/my-private-keys/timestamp/id11.private containing keys for all the various TUF roles. Note that these keys are stored outside of the repository proper. 3. Create the initial TUF metadata and construct an index using # hackage-repo-tool bootstrap \ --repo ~/my-secure-repo \ --keys ~/my-private-keys This will create a directory `~/my-secure-repo/index` containing the `.cabal` files (extracted from the package tarballs) and TUF metadata for all packages ~/my-secure-repo/index/basic-sop/0.1.0.5/basic-sop.cabal ~/my-secure-repo/index/basic-sop/0.1.0.5/package.json ~/my-secure-repo/index/generics-sop/0.1.1.1/generics-sop.cabal ~/my-secure-repo/index/generics-sop/0.1.1.1/package.json ... and package the contents of that directory up as the index tarball `~/my-secure-repo/00-index.tar.gz`; it will also create the top-level metadata files ~/my-secure-repo/mirrors.json ~/my-secure-repo/root.json ~/my-secure-repo/snapshot.json ~/my-secure-repo/timestamp.json 4. The timestamp and snapshot are valid for three days, so you will need to resign these files regularly using # hackage-repo-tool update \ --repo ~/my-secure-repo \ --keys ~/my-private-keys You can use the same command whenever you add any additional packages to your repository. 5. If you now make this directory available (for instance, by pointing Apache httpd at it) you'll be able to use `cabal` to access it remotely by defining an appropriate [`repository` stanza](https://www.haskell.org/cabal/users-guide/installing-packages.html#using-secure-repositories): repository my-secure-repo url: http://packages.example.org/ secure: True root-keys: 2ae741f4c4a5f70ed6e6c48762e0d7a493d8dd265e9cbc6c4037dfc7ceaec70e 32d3db5b4403935c0baf52a2bcb05031784a971ee2d43587288776f2e90609db eed36d2bb15f94628221cde558e99c4e1ad36fd243fe3748e1ee7ad00eb9d628 key-threshold: 2 Note that the keys in example above must be replaced: You need to copy the root key IDs from your generated `root.json` file (or you can set `key-threshold` to 0 if you're aware of the security implications)