Benjamin Hipple edited this page Oct 21, 2016 · 24 revisions


To build the latest Hackage code:

git clone
cd hackage-server
cabal install --only-dependencies
cabal configure -O0
cabal build


The following commands run the server in the current build tree:

cabal run -- hackage-server init --static-dir=datafiles/
cabal run -- hackage-server run  --static-dir=datafiles/

By default the server runs on port 8080 with the following settings:

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

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

The server can be killed by using:


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


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

rm -rf state/

Note that the datafiles/ and state/ directories differ: datafiles is for static html and other files. The state directory holds information about the database, using acid-state.

Creating users & uploading packages

List of registered users:


Register new users:


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

  • admins http://localhost:8080/users/admins/ -- administrators can do things with user accounts like disabling, deleting, changing other groups etc.
  • trustees http://localhost:8080/packages/trustees/ -- trustees can do janitorial work on all packages
  • mirrors http://localhost:8080/packages/mirrorers/ -- for special mirroring clients that are trusted to upload packages
  • per-package maintainer groups http://localhost:8080/package/foo/maintainers -- users allowed to upload packages
  • uploaders http://localhost:8080/packages/uploaders/ -- for uploading new packages


There is a client program included in the hackage-server package called hackage-mirror. It's intended to run against two servers, syncing all the packages from one to the other, e.g. getting all the packages from the old hackage 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 via http://localhost:8080/packages/mirrorers/
  2. Create a config file that contains the source and target servers. Assuming you are cloning the packages on locally, create the file servers.cfg:
source "hackage"
  type: hackage2

target "mirror"
  uri: http://admin:admin@localhost:8080/
  type: local

  post-mirror-hook: "shell command to execute"

Recognized types are hackage2, secure and local. The target server name was displayed when you ran

   hackage-server run.
  1. 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 of trouble. You can also do more robust and continuous mirroring. Use the flag --continuous. It will sync every 30 minutes (configurable with --interval). In this mode it carries on even when some packages cannot be mirrored for some reason and remembers them so it doesn't try them again and again. You can force it to try again by deleting the state files it mentions.

Building Documentation

There is another program included in the hackage-server package called hackage-build. It's used to build all documentation for new packages on a given hackage-server.

To use it:

  1. Add a user to the trustees group by navigating to http://localhost:8080/packages/trustees/
  2. Run hackage-build init: hackage-build init http://localhost:8080. It will prompt you for a username and password to use when uploading documentation.
  3. Run hackage-build build: hackage-build build. The available flags can be viewed via --help


  • Old URIs - the documents and scripts in hackage-scripts' directory tree
  • URIs - the planned new URIs and how to interact with them
  • Architecture - ideas and implementations for internal code organization
  • Command Line - how to use the command line interface
  • Switchover - Roadmap for hackage-server and the eventual switch to it.

People to ask

You should join the cabal-devel mailing list. There are a number of people there who are interested or are working on bits of hackage. That's the place to ask questions, post patches for review etc.

As for specific people, ask Duncan (dcoutts on irc) and Matt (Gracenotes on irc). Duncan knows the general design ideas and strategy. Matt did his GSoC project in 2012 on improving the server.

There is a #hackage irc channel where you will find some interested people.

Administrating users on

Making a release

See the separate Making a release page for instruction on how to make a release and update This is obviously only for people with permission to make a release!

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.