HepForge user guide

This is the guide to the services provided by HepForge. Please check here and in the FAQ if you have a problem with the system. If you can't find an answer there, email us at admin@hepforge.org.

Shell account and filespace

Your HepForge account gives you full Unix shell access to our server, with user privileges: login by SSH'ing to username@login.hepforge.org on port 222. You have personal webspace, if you want to use it, at http://users.hepforge.org/~username which can be accessed by creating a personal public_html directory containing HTML files: mkdir ~/public_html; touch ~/public_html/index.html should do the trick. These pages will be visible on the Web at http://users.hepforge.org/~username/.

Project information

Each project has a home directory located at /hepforge/home/projname: the files in this directory should be group writeable. This contains a directory called project-config, in which various configuration files for the project are contained. You can edit these files, but be careful!

Aside from the configuration files for the Trac bug tracker and wiki system, your ~projname/project-config area contains the htpasswd and htgroup files for password-protecting areas of your Web space (see the Apache documentation for more information) and a project.xml file.

project.xml

The ~projname/project.xml file is used to define various features of your project. At the moment it is mainly used to define a "display name" and a short description for your project: these are used when generating the default title for HepForge web pages and in the project and download lists. In future, the "keywords" and "categories" elements in the XML file will be used for project categorisation and searching: we'll let you know how that works when we've decided!

Web space

You have project web space in /hepforge/home/projname/public_html. This can be viewed by pointing your Web browser to http://projname.hepforge.org/. For the most part, the HepForge project web space is just like any normal web space, but there are a few special features:

  • A small HepForge "branding bar" is added to the top of each page;
  • Each page has some simple styling information associated with it. You can over-ride this if you want;
  • Basic HTML tags will be added to the top and bottom of each page if they aren't already there;
  • You can use PHP and CGI scripts to generate page content, which will run as the project user;
  • There is a simple mechanism for including a static header and footer on each page.

To expand on this last point, if you create a directory in your web area called "include" and place files in it called "header" and "footer", these files will be statically added to the top and bottom of every page respectively. This is a convenient way to add the HTML <head> section and a navigation menu to your site without having to write it on every page.

One unexpected feature of the HepForge web space is that Web sites written using "frames" will not display properly. This is due to the way that the HepForge Web server processes the pages you write, merging generic HepForge structures and definitions with the user-provided part of the page. In future we hope to make the degrading more "graceful". For now we'll justify the lack of functionality by pointing out that frames have plenty of useability issues of their own and that a lot of Web development guides (specifically, the ones that know what they're talking about) recommend not using them.

Version control systems

UPDATE: HEPForge now uses phabricator to manage VCS systems, this also allows projects to create their own repos. The documentation below is only for older projects.

We encourage you to use a code management system. This will keep a record of all the changes you make to your code and allows roll-backs to previous known-good versions should something go wrong. Code management systems also allow several different developers to work on the same code at the same time, while minimising conflicts and change-merging difficulties. Lastly, you can "tag" particular states of your code so that they are easily retrieved, for example when you make a new release.

HepForge now provides official support for the Subversion, Mercurial and Git version control systems. For new projects we recommend using Mercurial, a good introduction is at http://hginit.com/.

We're happy to help with version control issues, particularly if it'll help introduce new developers to this essential feature of robust development! However, before contacting us with queries, you should read the available documentation.

Your HepForge Subversion repository

If you don't pick a version control system, your project automatically has an SVN repository on HepForge, stored on the filesystem at /hepforge/svn/projname. If you want to restrict access to areas of this repository to particular authenticated users, you can use the svnserve.conf file, which is located in the conf directory of the repository (and is also symlinked from your project's project-config directory).

Users wanting to access your repository can use either the svn+ssh protocol or http. Commits are currently only possible over svn+ssh, which also requires a user account on HepForge so this is the advised protocol for project developers. HTTP is currently mainly useful for anonymous checkouts. The SVN path for svn+ssh developer access is svn+ssh://svn.hepforge.org/hepforge/svn/projname/.... SVN has a tendency to want to make two or three SSH connections, so you may get quite a few password prompts: setting up public key based SSH access is advised if you'll be doing a lot of svn+ssh access.

For HTTP access you can view your repository via the Web by pointing your web browser at http://projname.hepforge.org/svn/.... The same path can be used as an argument to the svn command line program.

Finally, you can view your SVN repository by using the neat viewer built into your project's Trac system - more about that later.

You can also use these URLs with SSL encryption if you wish: to do so, replace the http with https in the URLs above.

Mailing lists

By default, when we create a project, we will set up one mailing list, with names projname@projects.hepforge.org. On request, we'll also set up projname-announce@projects.hepforge.org. The projname@projects.hepforge.org list is the contact list for project administrators and the projname-announce@projects.hepforge.org list is for you to keep users of your project informed of new versions or other useful developments. If required, we can also set up additional lists with suffixes other than "announce", but all lists for a given project will be prefixed with the project name.

You can manage your own mailing lists using the Mailman system: this will allow you to specify, for example, whether the list is open or moderated (the admin contact list should be open, the announce list should be moderated, and if for example you set up a discussion list, that should be open too).

Please note that you shouldn't send large attachments to the HepForge lists: the lists have message size quotas, which are easily overflowed by binary attachments.

Download manager

When you release a new version of your code, the "HepForge way" is to place it in the /downloads directory of your project home area, with a filename of the form name-x.y.z.tar.gz (other archive formats, e.g. .zip, can also be used). The name part can include any characters other than a minus (dash) character followed by a digit: this is used to indicate the division between name and version code. The version code can contain as many "levels" as you wish, though the threefold x, y, z form above is the most popular. The x, y, z variables can each have more than one digit and will be sorted appropriately: for example, "proj-2.0.1.tar.gz" is a less recent version of the "my-proj" code than "my-proj-10.0.1.tar.gz".

The archived code will be made available through a Web listing at http://www.hepforge.org/downloads and archive files can be linked to directly at http://www.hepforge.org/archive/projname/archive-filename.

Bug tracker

UPDATE: HEPForge now recommends using the built in phabricator bug system. The documentation below is only for older projects.

All HepForge projects have access to a copy of the Trac bug tracking system, located at https://projname.hepforge.org/trac/. Trac includes tracking of "tickets" (i.e. bug reports), as well as management of project milestones, integration with version control for your project's source code and a wiki, as described briefly in the next section.

Trac integrates very nicely with the rest of the HepForge system: users are authenticated using their Hepforge logins, additional users can be added in the standard Apache htpasswd and htgroup files. These authentication files are stored in your project configuration area (/hepforge/home/projname/project-config) as described in the corresponding FAQ entry. Project configuration is performed using an interactive system from the command shell, called trac-admin, which is started as follows:

trac-admin /hepforge/projconf/projname/trac

You may also find it useful to configure Trac's appearance and behaviour using the trac.ini file located in .../project-config/trac/conf/. Using trac-admin and configuring Trac's ini file are described in great (and clear) detail in the Trac project wiki.

Note that SSL encryption is available for all HepForge pages and we force all Trac sessions to use it. Without SSL encryption, your project area login password will be sent across the internet in plain text and could easily be "sniffed". To use SSL encryption, make sure that the start of the web address in your browser reads https rather than just http. Your browser will probably also show a lock icon somewhere to indicate the security level.

Wiki

The Trac bug tracking system also includes a wiki, which integrates fully with the bug tracking features. A wiki is a collaborative documentation system, which uses a simplified markup language to produce web pages. Setting up users with different permissions to add, edit, delete (and so on) wiki pages, is also performed using the trac-admin script or Trac's admin webpage, so you should check out the Trac project wiki for wiki questions, too. If you can't find what you're looking for, send an email to us at admin@hepforge.org and we'll see if we can help.

Software build/configuration systems

This will be updated once we have a better user guide.