Quick intro
-----------

* Install as described in INSTALL.txt

* Run instancemanager once to create a .instancemanager directory in ~

* Edit userdefaults.py in ~ for only the common basis for all your sites
(example, Zope path, default admin and password for new sites)

* Copy userdefaults.py in ~ to <project>.py (typically "customername.py")
and customize (override) for that project (port, plone site name, products, etc.)

* Now this will do the full setup for your site. ONLY do it when you want a TOTALLY fresh start::

instancemanager fresh <project> # NOT <project>.py -

* to stop zope::

instancemanager -z stop <project>

* to start in foreground::

instancemanager -z fg <project>

* to reinstall products::

instancemanager --products <project>

or, if you want to make sure everything's OK::

instancemanager --products --manifest <project>

The last gets you a (wide) manifest that can help diagnose product
version issues and collisions from bundles.

More details below.


Details
-------

Setting up a zope instance, symlinking to all the products, extracting
product tarballs, copying over a snapshot Data.fs from the customer's
website, restarting zope, clicking around in the quickinstaller: *it
can all be done by hand*.

Instancemanager is a handy utility program that manages your
development zope instances:

* Creates clean, fresh instances in your standard location.

* Copies over a prepared Data.fs if desired.

* Makes products available in the 'Products/' directory from a variety
of sources (.tgz, .tgz bundles, svn, symlinking).

* Restarts your zope and reinstalls your products.

* Does the Data.fs copy, the product availability and the reinstall in
one step, giving you a real fresh instance without leftover junk.

* Make backups and restores of the instance database to a directory. By
default backups are stored in ~/backups/<project> which will be created if
it doesn't exist. You can also set how many full backup you want to keep.
Older backups will automatically be deleted to reduce disk usage.

If you're the kind of good developers that's also a lazy developer,
you don't want to do this repetitive stuff by hand. That's where the
**instance manager** jumps in. 'instancemanager --create yourproject'
creates an instance in your default location. 'instancemanager
fresh yourproject ' gives you a freshly prepared products directory, a
freshly copied pre-made Data.fs (if you've got one) and it presses the
quickinstaller buttons you want pressed.

For instance, individual product sources can be:

* A '.tgz' file (like FCKeditor or qGoogleSitemaps).

* A '.tgz' bundle (like plone or ploneformmailer).

* A symlink (most probably to an svn directory, for instance your
current customer development product).

* A symlink to a bundle directory (most probably an svn bundle, for
instance the latest plone 2.5).

Configuration is handled in a layered manner. Instancemanager has its
own defaults. You can overwrite these global defaults locally ("I
always store my instances in my homedir instead of '~/instances/'").
And there's an per-project config file where you can list
exceptions. And of course the passwords and desired products and so.

If you specify the ID of your plone root ('plone_site_name'), the
instancemanager attempts a quick-reinstall of your products when
running the "fresh" or "soft" targets. Real handy during
development. It even migrates plone to a newer version when
needed. I'm able to migrate http://vanrees.org/ from a plone 2.1
website to plone 2.5, including migration, with just a call to
'instancemanager fresh vanrees '. And it updates a couple of other
products too, while it's at it. This removes the need for much by-hand
action when testing migrations or when doing installer updates on your
product.

When you have specified a plone_site_name and a PloneSite of that name
does not exist yet, instancemanager tries to create that. Works for
plone 2.1 and 2.5. It has some oddities still though. When the
script has run for the first time, a 'bin/zopectl status' cannot find
the zope process, though it *is* running. Shutting it down via the
Control Panel and then restarting it from the command line seems the
best option here. Some testing is needed to improve this. Upon
trying again after minor changes it seems to work fine actually.
Still: consider this experimental, so: start experimenting. :)


Usage
-----

Usage::

Usage: instancemanager [options] [multi-action] <project>
multi-action: default ones are 'fresh' and 'soft'.

options:
--version show program's version number and exit
-h, --help show this help message and exit
-v, --verbose Show all logging messages.
-q, --quiet Only show error messages.
-m, --manifest Print Manifest of installed Products and collisions
--activate Print workingenv activation command
-b, --backup Backup the instance database (incremental backup).
--changeown Action that changes ownership of some documents.
--copydatafs Copy over a fresh, prepared, 'Data.fs'.
--create Create a zope instance for your project.
--pack Action that packs your database.
--printconfig Print the configuration for this project.
--products Rebuild the Products/ directory .
-r, --reinstall Action that quickreinstalls your products.
--repozo=REPOZO Other backup/restore tasks with repozo.
--restore Restore the database from the regular backup.
--restore-date=DATE Restore situation at DATE from regular backup.
--rewriterule Print out an apache rewriterule.
--runcommand Run external command.
-t PRD, --test=PRD Runs tests for product PRD (use MAIN for main
products).
-u CMD, --uninstall=CMD
Action that uninstalls a given product
--updatesources Update the working-copies of all sources.
--upgradezope Update the zope.conf used for your instance
--zeo=CMD Runs your zeo server's 'bin/zeoctl CMD'.
-z CMD, --zope=CMD Runs your instance's 'bin/zopectl CMD'.

Instancemanager can be installed using the normal `python setup.py
install` magic. Note that (at least on my computer), the actual
`instancemanager` script gets installed somewhere deep in the python
library directory instead of in a normal executable place. To remedy
that, do something like::

sudo python setup.py install --install-script=/usr/local/bin

The first time you run instancemanager (just type `instancemanager`
and press Enter), it creates a `.instancemanager` directory in your
home directory. There you'll find a `userdefaults.py` that you can
customise to your local needs.

Following that, create a file called `<yourproject>.py` (can be empty)
in the `.instancemanager/` directory, customising that perhaps with
project-specific settings (just copy the few items that you want to
change from `userdefaults.py`). Then you're set for typing in
`instancemanager --create yourproject`. Or perhaps even handier,
`instancemanager yourproject fresh`, as that does everything from
creating the instance to installing your products.

Instancemanager creates an `instancemanager.log` logfile in
`~/.instancemanager/`, btw, should you want to get an information
overload about what's going on. (The first time you run it, it creates
the logfile in the current directory as `~/.instancemanager` doesn't
exist yet).

If you want the bash shell to complete your instancemanager commands,
read the instruction on the top of the bash_completion file.

Actions that can be performed on instances and products.


Everything that is handy to have as a single unit of action is turned
into an Action. They can be quite small (just stopping zope), but
that's OK. Being able to say 'instancemanager myproject stop' from
anywhere without having to go to the instance directory to say
'bin/zopectl stop' saves on the number of terminals you have to keep
open.



`--activate`
Print workingenv's `activate` script.

The activate script needs to be run with `. PATH/bin/activate`
or `source PATH/bin/activate`. All we can do to make it simpler
is to just print the output of activate so that a `source
instancemanager PROJECT --activate` does the same


`--backup`
Backup the Zope Database of the instance.

This action relies on the backup_basedir_template variable to store the
backups. By default, the backups are incremental unless there's
been a pack.


`--changeown`
Action that changes ownership of some documents.


`--copydatafs`
Copy over a fresh, prepared, Data.fs.

When you are developing, you might have an existing Data.fs file
you want to use. For instance the current product database of your
customer project that you copied for debugging purposes.

Instancemanager looks for a database in, by default,
'~/instances/datafs/yourproject.fs'. You can change this in your
config. The datafs action just copies this file to the instance's
'var/' directory.


`--create`
Create a zope instance, possibly including a zeo server.

This will create a zope instance for you using the familiar
'mkzopeinstance' command. The instance will be the location you
specified in your config file. By default it will be
'~/instances/projectname/'.

Also, the zope.conf will be adapted in some places, like enabling
debug mode and verbose security (for zope 2.8 and up). The port,
username and password will be set according to the config file.


`--ipython`
Start ipython.


`--pack`
Action that packs your database.


`--printconfig`
Print the configuration.

'instancemanager yourproject printconfig' shows the configuration
for your project as intancemanager understands it.


`--products`
Rebuild the Products/ directory from scratch.

**Warning**, this *does* remove everything in 'Products/' before
copying over new versions. That is the whole purpose. :-) If it
isn't your purpose, you shouldn't really be using this program.

You can configure a variety of sources in your
configuration. Every source is an instruction for the "products"
action. Possible sources are svn links and .tgz files, both for
single products or for bundles.


`--reinstall`
Action that quickreinstalls your products.

This used to depend on the presence of a specific script in your
zope root that called the actual quickinstaller. There's a generic
script that gets used now, however.

For more info see the quickinstallerscript documentation.


`--repozo`
Perform a variety of repozo backup/restore actions.

--backup and --restore are fine, but there are more diverse things
that can be done with repozo, this action allows some of them.


`--restore`
Restore the Zope Database of the instance.

This action relies on the backup_basedir_template variable to restore the
backups from.


`--restore-date`
Restore the Zope Database of the instance by date

This action relies on the backup_basedir_template variable to restore the
backups from.


`--rewriterule`
Print out a RewriteRule for use in your apache config.

Also include some helpful pointers to information.


`--runcommand`
Run external command action

This action calls external script using os.system call
Script is called for all instanceDirs.


`--test`
Action for calling zopectl with a test command.


`--uninstall`
Action that uninstalls a given product from your instance.


`--updatesources`
Action for updating/switching svn checkouts


`--upgradezope`
Copies over the zope.conf or regenerates it based on the current
configuration and copies over the zopectl from the correct skeleton.
Upgrade your instance in 2 steps:

1. Update the Zope version in your project.py
2. run instancemanager --upgradezope


`--zeo`
Action for calling zeoctl.


`--zope`
Action for calling zopectl.