# `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)