$Id$

This file details how to use the rpkidemo script with the portal-gui.

Requirements
============

- the portal-gui must be run using apache with mod_wsgi
- for security, mod_ssl is recommended

Fedora:
	$ yum install httpd mod_wsgi mod_ssl

Setup
=====

- Follow the steps in detailed in the README file to set up the portal-gui
  for the self-hosted resource handle that will act as parent to all other
  users.

- After running "make" in $top/portal-gui, there will be a file named
  $top/portal-gui/apache/zmyrpki.conf.  This is a configuration file for
  apache which does most of the work configuring the portal-gui to run
  under mod_wsgi.

  You may need to edit the paths for Django if they are installed in a
  different location on your host.  Note that this is only necessary if
  you wish to use the Django admin web console.  The portal-gui itself
  will operate correctly even if this path is wrong.

  Fedora:
	cp $top/portal-gui/apache/zmyrpki.conf /etc/httpd/conf.d/

- $top/portal-gui/rpkigui/settings.py needs to be edited to allow it to make
  use of the external user authentication provided by apache.  There are two
  places where lines need to be uncommented:

  a) in MIDDLEWARE_CLASSES, uncomment:

	#'django.contrib.auth.middleware.RemoteUserMiddleware',

  b) uncomment the AUTHENTICATION_BACKENDS section:

	#AUTHENTICATION_BACKENDS = (
	#	'django.contrib.auth.backends.RemoteUserBackend',
	#)

- Run the `adduser' script to configure the portal-gui with a new account.  You
  need to specify the user's parent on the command line, as this acts as an
  implicit authorization when rpkidemo uploads its identity.xml.  This script
  will be located in $prefix/share/portal-gui/scripts/adduser after
  installation.

- At this point the portal-gui is ready to accept connections from rpkidemo.
  On the end-user machine, invoke $top/scripts/rpkidemo.  rpkidemo will query
  for the username and password, which is what you configured in the `adduser'
  step above.  rpkidemo will build openssl if required, then perform the
  initializations steps described in $top/rpkid/doc/MyRPKI.  Once the initial
  setup is completed, and list_resources has been run, you should see the new
  user listed as a child of the parent handle specified in the `adduser' step
  above.  Now you should be able to delegate resources to the new user and use
  the portal-gui in the usual manner.

Testing with yamltest
=====================

- you can specify
	CONFDIR=$top/rpkid/tests/yamltest.dir
  to make the portal-gui be a front-end for the resource handles created by
  a yamltest run.

- you will need to periodically run the lists_resources script in
	$top/rpkid/tests/yamltest.dir/RIR
  to update the portal-gui database with the current state of children and
  received resources

- the web server runs as the `apache' user by default under Fedora, which won't
  have permissions to write to the yamltest.dir directory.  easiet thing to do
  is chown the entire tree so that the `apache' user has full access:

	# chown -R apache $top/rpkid/tests/yamltest.dir