Table of Contents
=================

 * Prerequisites
 * Installation
 * Submin environment
 * Git support (optional)
 * Apache
 * Login to submin
 * Final touches


Prerequisites
=============

Submin is tested with Python 2.x exclusively, it probably does not (yet) work
with Python 3.x. If you have fixes for 3.x, please let us know.

Depending on your choices, you also need either git or subversion, and
optionally trac for ticket supports.

If you want subversion, you also need apache. If only git is needed, you can
also install nginx.


Installation
============

Installing from debian package: 

    see http://supermind.nl/submin/download.html


Installing from source:

    Download tarball from http://supermind.nl/submin/download.html
    Extract the tarball
    execute: python2 setup.py install
    => submin will be installed in site-packages, an executable submin2-admin
       will be installed in /usr/bin


Create submin environment
=========================

Multiple submin installations can co-exist on the same server. Therefore, for
each installation, an environment must be created. All data (repositories,
configuration, etc) are located in one directory, for example /var/lib/submin.

To create a submin environment, follow instructions after executing:

    submin2-admin /var/lib/submin initenv your@email.address

For help on submin-admin, execute the following command:

    submin2-admin /var/lib/submin help
    submin2-admin /var/lib/submin help <subcommand>


Git support (optional)
======================

Git support requires a special user to be created and some additional settings.
Run the following command as root and follow the instructions:

    submin2-admin /var/lib/submin git init


Configure Webserver
===================

Submin2 can create all kinds of configs for you, for both apache and nginx.
If you only need git you can install nginx, otherwise you need to install
Apache.

For advanced usage, you can mix Apache and NGINX config!


Configure Apache
----------------

After running initenv above, the apache config files are created. If you want
to create them again for any reason, run the following command:

    submin2-admin /var/lib/submin apacheconf create all

Now to activate the submin2 website, the configuration should be included into
Apache2. To use for example CGI and SVN, execute the following commands as
root (on Debian systems with Apache <2.4):

    ln -s /var/lib/submin/conf/apache-webui-cgi.conf /etc/apache2/conf.d/
    ln -s /var/lib/submin/conf/apache-svn.conf /etc/apache2/conf.d/

For Debian systems with Apache 2.4+, link the 2.4 versions:

    ln -s /var/lib/submin/conf/apache-2.4-webui-cgi.conf /etc/apache2/conf-available/
    ln -s /var/lib/submin/conf/apache-2.4-svn.conf /etc/apache2/conf-available/
    a2enconf apache-2.4-webui-cgi.conf
    a2enconf apache-2.4-svn.conf

Now restart your webserver to activate the new settings.

    apachectl restart


Configure NGINX
---------------

To generate NGINX config files, run the following command:

    submin2-admin /var/lib/submin nginxconf create all

To activate submin2 in nginx, see instructions in the generated nginx config 
file /var/lib/submin/conf/nginx-webui-wsgi.conf


Login to your Submin2 website
=============================

The email-address you have provided with the 'initenv' command above has
received a password reset email. Read your email and click the link. You will
get another email with the password. You can use this to login.

If you did not receive an e-mail, it could be that your server could not
send it, or that the mail was blocked somewhere. Please run diagnostics:

    submin2-admin /var/lib/submin diagnostics email

If you followed the steps there and you still can't get it to work, please
make sure you can send emails from the server (for example, test with 'mail'
on the command line) and then use the 'forgot password' functionality to
request a password (for the user 'admin').


Advanced configuration
======================

For more advanced configuration, see the CONFIGURATION file included in
the source code. To find an online version, please see:

https://ssl.supermind.nl/collab/projects/submin/browser/CONFIGURATION


Troubleshooting
===============
To find the common misconfiguration problems, Submin offers diagnostics. There
is a web-ui version and a command-line version. The web-ui version can be
found in the sidebar under 'SYSTEM', the command-line version can be run as:

    submin2-admin /var/lib/submin diagnostics

For more information, see the help of diagnostics ('help diagnostics' instead
of 'diagnostics).


Final touches
=============

Be sure to check the Diagnostics page after logging in as admin, it will help
with fine-tuning your configuration for your installation.

With new submin versions, sometimes new checks are added on this page, so be
sure to check back here after upgrading submin.


Happy subminning :)