Repository files navigation

This is thehackage-server code. This is what powershttp://hackage.haskell.org, and many other private hackage instances. Themaster branch is suitable for general usage. Specific policy and documentation for the central hackage instance exists in thecentral-server branch.

hackage-server depends onlibgd,zlib, and other system libraries. You'll also needlibbrotli-dev for enabling tests.

You can use the Nix package manager to provide these dependencies, or install them manually.

If you have the Nix package manager installed, you can build and runhackage-server without manually installing any dependencies:

$ nix run'state' state-dir already existshackage-server: Ready! Point your browser at http://127.0.0.1:8080

If the requiredstate directory does not already exist,nix run will create and initialize it.

Theflake.nix is implemented withsrid/haskell-flake.

Alternatively, open thenix develop shell:

$ nix develop(in develop shell)# if state directory does not already exist$ cabal v2-run -- hackage-server init --static-dir=datafiles --state-dir=state$ cabal v2-run -- hackage-server run --static-dir=datafiles --state-dir=state \    --base-uri=http://localhost:8080 \    --required-base-host-header=localhost:8080 \    --user-content-uri=http://127.0.0.1:8080hackage-server: Ready! Point your browser at http://localhost:8080

This copies packages from real Hackage Server to local Hackage Server.

Add the defaultadmin user to themirrorers group here:http://localhost:8080/packages/mirrorers/

Then

 $ nix run .#mirror-hackage-server

Please note this Appcannot be rundirectly from GitHub like this:

nix run github:haskell/hackage-server -- init --static-dir=datafilesnix run github:haskell/hackage-server -- run --static-dir=datafiles --base-uri=http://127.0.0.1:8080

becausehackage-server expects the directoriesstate anddatafiles to exist in the working directory.

You can also install dependencies manually via your operating system's packagemanager.

You'll need to do the following to gethackage-server's dependencyhs-captcha (and transitivelygd) to build:

• Mac OS X

  brew install libgd

• Ubuntu/Debian

  sudo apt-get updatesudo apt-get install unzip libgd-dev

• Fedora/CentOS

  sudo dnf install unzip libgd-devel

• Nix/NixOS

  nix-shell --packages gd

• Ubuntu/Debian

  sudo apt updatesudo apt install libbrotli-dev

• Fedora/CentOS

  sudo dnf install brotli-devel

• Fedora/CentOS

  sudo dnf install openssl-devel

• Mac OS X

  brew install zlib

• Ubuntu/Debian

  sudo apt-get updatesudo apt-get install zlib

• Fedora/CentOS

  sudo dnf install zlib

• Nix/NixOS

  nix-shell --packages zlib

In addition to the above commands, you'll need to run

brew install pkg-config

After running the abovebrew install commands, you also need to updatecabal.project.local with the following:

cat>> cabal.project.local<<EOFpackage gd  extra-include-dirs:$(echo$(brew --prefix)/Cellar/gd/*/include)  extra-lib-dirs:$(echo$(brew --prefix)/Cellar/gd/*/lib)$(echo$(brew --prefix)/Cellar/libpng/*/lib)$(echo$(brew --prefix)/Cellar/jpeg-turbo/*/lib)$(echo$(brew --prefix)/Cellar/fontconfig/*/lib)$(echo$(brew --prefix)/Cellar/freetype/*/lib)constraints:  , HsOpenSSL +use-pkg-configEOF

Out of the box the server comes with some example keys andTUF metadata. The example keys are inexample-keys/; these keys were used to create

datafiles/TUF/root.jsondatafiles/TUF/mirrors.jsondatafiles/TUF/timestamp.privatedatafiles/TUF/snapshot.private

While these files will enable you to start the server without doing anythingelse, you should replace all these files before deploying your server. In theremainder of this section we will explain how to do that.

The first step is to create your own keys using thehackage-repo-tool:

hackage-repo-tool create-keys --keys /path/to/keys

Then copy over the timestamp and snapshot keys to the TUF directory:

cp /path/to/keys/timestamp/<id>.private datafiles/TUF/timestamp.privatecp /path/to/keys/snapshot/<id>.private  datafiles/TUF/snapshot.private

Create root information:

hackage-repo-tool create-root --keys /path/to/keys -o datafiles/TUF/root.json

And finally create a list of mirrors (this is necessary even if you don't haveany mirrors):

hackage-repo-tool create-mirrors --keys /path/to/keys -o datafiles/TUF/mirrors.json

Thecreate-mirrors command takes a list of mirrors as additional arguments ifyou do want to list mirrors.

In order for secure clients to bootstrap the root security metadata from yourserver, you will need to provide them with the public key IDs of your root keys;you can find these as the file names of the files created in/path/to/keys/root (as well as in the generated root.json under thesigned.roles.root.keyids). An examplecabal client configuration might looksomething like

repository my-private-hackage  url: http://example.com:8080/  secure: True  root-keys: 865cc6ce84231ccc990885b1addc92646b7377dd8bb920bdfe3be4d20c707796             dd86074061a8a6570348e489aae306b997ed3ccdf87d567260c4568f8ac2cbee             e4182227adac4f3d0f60c9e9392d720e07a8586e6f271ddcc1697e1eeab73390  key-threshold: 2

Note that if you elect to not use a secure client, the hackage server will notprovide your client the most recent versions of packages from its index. Thecabal-version:2.0 format packages are thus only available in the newer securerepository mode. SeeIssue #4625for further information.

cabal installhackage-server inithackage-server run

If you want to run the server directly from the build tree, run

cabal v2-run -- hackage-server init

once to initialise the state. After that you can run the server with

cabal v2-run -- hackage-server run --static-dir=datafiles/ --base-uri=http://127.0.0.1:8080

By default the server runs on port8080 with the following settings:

URL:      http://localhost:8080/username: adminpassword: admin

To specify something different, seehackage-server init --help for details.

Thehttp://127.0.0.1:8080/packages/uploaders/edit is used to add users(e.g.admin) toUploaders group.

The server can be stopped by usingControl-C.

This will save the current state and shutdown cleanly. Running againwill resume with the same state.

To reset everything, kill the server and delete the server state:

rm -rf state/

Note that thedatafiles/ andstate/ directories differ:datafiles is for static html, templates and other files.Thestate directory holds the database (usingacid-stateand a separate blob store).

• Admin front-end:http://localhost:8080/admin
• List of users:http://localhost:8080/users/
• Register new users:http://localhost:8080/users/register

Currently there is no restriction on registering, but only an adminuser can grant privileges to registered users e.g. by adding them toother groups. In particular there are groups:

• adminshttp://localhost:8080/users/admins/ -- administrators cando things with user accounts like disabling, deleting, changingother groups etc.
• trusteeshttp://localhost:8080/packages/trustees/ -- trustees cando janitorial work on all packages
• mirrorshttp://localhost:8080/packages/mirrorers/ -- for specialmirroring clients that are trusted to upload packages
• per-package maintainer groupshttp://localhost:8080/package/foo/maintainers -- users allowed toupload packages
• uploadershttp://localhost:8080/packages/uploaders/ -- foruploading new packages

There is a client program included in thehackage-server package calledhackage-mirror. It's intended to run against two servers, syncing all thepackages from one to the other, e.g. getting all the packages from the oldhackage and uploading them to a local instance of a hackage-server.

To try it out:

1. On the target server, add a user to the mirrorers group viahttp://localhost:8080/packages/mirrorers/.

2. Create a config file that contains the source and targetservers. Assuming you are cloning the packages onhttp://hackage.haskell.org locally, create the fileservers.cfg:

   source "hackage"  uri: http://hackage.haskell.org  type: securetarget "mirror"  uri: http://admin:admin@localhost:8080  type: hackage2  post-mirror-hook: "shell command to execute"

   Recognized types arehackage2,secure andlocal.The target server name was displayed when you ran.

   Note, the target mustnot have a trailing slash, or confusionwill tend to occur. Additionally, if you have ipv6 setup on themachine, you may need to replacelocalhost with127.0.0.1.

   Also note that you should mirrorfromhackage2 orsecuretypically and mirrortohackage2. Only mirroring fromsecurewill include dependency revision information.

   hackage-server run

3. Run the client, pointing to the config file:

   hackage-mirror servers.cfg

   This will do a one-time sync, and will bail out at the first sign oftrouble. You can also do more robust and continuous mirroring. Use theflag--continuous. It will sync every 30 minutes (configurable with--interval). In this mode it carries on even when some packagescannot be mirrored for some reason and remembers them so it doesn'ttry them again and again. You can force it to try again by deletingthe state files it mentions.