split instance initialisation into two steps...

...allowing config changes before the database is initialised.

Author: Richard Jones

CHANGES.txt

@@ -30,6 +30,8 @@ Feature:
  . reverting to dates for intervals > 2 months sucks
  . changed the default message list in issues to display the message body
  . applied patch #558876 ] cgi client customization
+ . split instance initialisation into two steps, allowing config changes
+   before the database is initialised.
 
 Fixed:
  . stop sending blank (whitespace-only) notes

doc/installation.txt

@@ -2,7 +2,7 @@
 Installing Roundup
 ==================
 
-:Version: $Revision: 1.6 $
+:Version: $Revision: 1.7 $
 
 .. contents::
 
@@ -106,7 +106,7 @@ Set aside 15-30 minutes.
       environment variable or specify the full path to
       the command in the next step.
 
-  c.  ``roundup-admin init``
+   c.  ``roundup-admin install``
 
       You will be asked a series of questions.  A description of
       the Roundup-provided templates can be found under the Overview_::
@@ -116,9 +116,21 @@ Set aside 15-30 minutes.
           Select template [classic]: classic
           Back ends: anydbm, bsddb
           Select backend [anydbm]: anydbm
+
+      You will now be directed to edit the instance configuration and
+      initial schema. See `Customizing Roundup`_ for details on configuration
+      and schema changes.
+
+   d.  ``roundup-admin initialise``
+
+      This step initialises the instance database. You will need to supply
+      an admin password at this step. You will be prompted:
+
           Admin Password:
                  Confirm:
 
+      Once this is done, the instance has been created.
+
 3. Each instance ideally should have its own UNIX group, so create
    a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
    you're using NIS).  To continue with my examples so far, I would

roundup/admin.py

@@ -16,9 +16,9 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: admin.py,v 1.10 2002-04-27 10:07:23 richard Exp $
+# $Id: admin.py,v 1.11 2002-05-23 01:14:20 richard Exp $
 
-import sys, os, getpass, getopt, re, UserDict, shlex
+import sys, os, getpass, getopt, re, UserDict, shlex, shutil
 try:
     import csv
 except ImportError:
@@ -249,15 +249,20 @@ def help_initopts(self):
         print _('Back ends:'), ', '.join(backends)
 
 
-    def do_initialise(self, instance_home, args):
-        '''Usage: initialise [template [backend [admin password]]]
-        Initialise a new Roundup instance.
+    def do_install(self, instance_home, args):
+        '''Usage: install [template [backend [admin password]]]
+        Install a new Roundup instance.
 
         The command will prompt for the instance home directory (if not supplied
         through INSTANCE_HOME or the -i option). The template, backend and admin
         password may be specified on the command-line as arguments, in that
         order.
 
+        The initialise command must be called after this command in order
+        to initialise the instance's database. You may edit the instance's
+        initial database contents before running that command by editing
+        the instance's dbinit.py module init() function.
+
         See also initopts help.
         '''
         if len(args) < 1:
@@ -291,18 +296,70 @@ def do_initialise(self, instance_home, args):
             if not backend:
                 backend = 'anydbm'
 
-        # admin password
-        if len(args) > 3:
-            adminpw = confirm = args[3]
+        # install!
+        init.install(instance_home, template, backend)
+
+        print _('''
+ You should now edit the instance configuration file:
+   %(instance_config_file)s
+ ... at a minimum, you must set MAILHOST, MAIL_DOMAIN and ADMIN_EMAIL.
+
+ If you wish to modify the default schema, you should also edit the database
+ initialisation file:
+   %(database_config_file)s
+ ... see the documentation on customizing for more information.
+''')%{
+    'instance_config_file': os.path.join(instance_home, 'instance_config.py'),
+    'database_config_file': os.path.join(instance_home, 'dbinit.py')
+}
+        return 0
+
+
+    def do_initialise(self, instance_home, args):
+        '''Usage: initialise [adminpw [adminemail]]
+        Initialise a new Roundup instance.
+
+        The administrator details will be set at this step.
+
+        Execute the instance's initialisation function dbinit.init()
+        '''
+        # password
+        if len(args) > 0:
+            adminpw = args[0]
         else:
             adminpw = ''
             confirm = 'x'
-        while adminpw != confirm:
-            adminpw = getpass.getpass(_('Admin Password: '))
-            confirm = getpass.getpass(_('       Confirm: '))
+            while adminpw != confirm:
+                adminpw = getpass.getpass(_('Admin Password: '))
+                confirm = getpass.getpass(_('       Confirm: '))
+
+        # email
+        if len(args) > 1:
+            adminemail = args[1]
+        else:
+            adminemail = ''
+            while not adminemail:
+                adminemail = raw_input(_('   Admin Email: ')).strip()
+
+        # make sure the instance home is installed
+        if not os.path.exists(instance_home):
+            raise UsageError, _('Instance home does not exist')%locals()
+        if not os.path.exists(os.path.join(instance_home, 'html')):
+            raise UsageError, _('Instance has not been installed')%locals()
+
+        # is there already a database?
+        if os.path.exists(os.path.join(instance_home, 'db')):
+            print _('WARNING: The database is already initialised!')
+            print _('If you re-initialise it, you will lose all the data!')
+            ok = raw_input(_('Erase it? Y/[N]: ')).strip()
+            if ok.lower() != 'y':
+                return 0
+
+            # nuke it
+            shutil.rmtree(os.path.join(instance_home, 'db'))
 
-        # create!
-        init.init(instance_home, template, backend, adminpw)
+        # GO
+        init.initialise(instance_home, adminpw)
 
         return 0
 
@@ -955,13 +1012,19 @@ def run_command(self, args):
         while not self.instance_home:
             self.instance_home = raw_input(_('Enter instance home: ')).strip()
 
-        # before we open the db, we may be doing an init
+        # before we open the db, we may be doing an install or init
         if command == 'initialise':
             try:
                 return self.do_initialise(self.instance_home, args)
             except UsageError, message:
                 print _('Error: %(message)s')%locals()
                 return 1
+        elif command == 'install':
+            try:
+                return self.do_install(self.instance_home, args)
+            except UsageError, message:
+                print _('Error: %(message)s')%locals()
+                return 1
 
         # get the instance
         try:
@@ -1061,6 +1124,9 @@ def main(self):
 
 #
 # $Log: not supported by cvs2svn $
+# Revision 1.10  2002/04/27 10:07:23  richard
+# minor fix to error message
+#
 # Revision 1.9  2002/03/12 22:51:47  richard
 #  . #527416 ] roundup-admin uses undefined value
 #  . #527503 ] unfriendly init blowup when parent dir

roundup/init.py

@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: init.py,v 1.18 2001-11-22 15:46:42 jhermann Exp $
+# $Id: init.py,v 1.19 2002-05-23 01:14:20 richard Exp $
 
 __doc__ = """
 Init (create) a roundup instance.
@@ -55,13 +55,12 @@ def copytree(src, dst, symlinks=0):
         else:
             install_util.copyDigestedFile(srcname, dstname)
 
-def init(instance_home, template, backend, adminpw):
-    '''Initialise an instance using the named template and backend.
+def install(instance_home, template, backend):
+    '''Install an instance using the named template and backend.
 
     instance_home - the directory to place the instance data in
     template - the template to use in creating the instance data
     backend - the database to use to store the instance data
-    adminpw - the password for the "admin" user
 
     The instance_home directory will be created using the files found in
     the named template (roundup.templates.<name>). A standard instance_home
@@ -102,12 +101,21 @@ def init(instance_home, template, backend, adminpw):
 from roundup.backends.back_%s import Database'''%backend
     open(os.path.join(instance_home, 'select_db.py'), 'w').write(db)
 
+
+def initialise(instance_home, adminpw):
+    '''Initialise an instance's database
+
+    adminpw    - the password for the "admin" user
+    '''
     # now import the instance and call its init
     instance = roundup.instance.open(instance_home)
     instance.init(password.Password(adminpw))
 
 #
 # $Log: not supported by cvs2svn $
+# Revision 1.18  2001/11/22 15:46:42  jhermann
+# Added module docstrings to all modules.
+#
 # Revision 1.17  2001/11/12 23:17:38  jhermann
 # Code using copyDigestedFile() that passes unit tests
 #