source: INSTALL

Last change on this file was 4694367, checked in by Michiel Holtkamp <git@…>, 3 years ago

Update INSTALL docs

  • Add instructions on how to use the command-line diagnostics.
  • Add link to CONFIGURATION for advanced configuration options (refs #355)
  • Property mode set to 100644
File size: 4.8 KB
Line 
1Table of Contents
2=================
3
4 * Prerequisites
5 * Installation
6 * Submin environment
7 * Git support (optional)
8 * Apache
9 * Login to submin
10 * Final touches
11
12
13Prerequisites
14=============
15
16Submin is tested with Python 2.x exclusively, it probably does not (yet) work
17with Python 3.x. If you have fixes for 3.x, please let us know.
18
19Depending on your choices, you also need either git or subversion, and
20optionally trac for ticket supports.
21
22If you want subversion, you also need apache. If only git is needed, you can
23also install nginx.
24
25
26Installation
27============
28
29Installing from debian package:
30
31    see http://supermind.nl/submin/download.html
32
33
34Installing from source:
35
36    Download tarball from http://supermind.nl/submin/download.html
37    Extract the tarball
38    execute: python2 setup.py install
39    => submin will be installed in site-packages, an executable submin2-admin
40       will be installed in /usr/bin
41
42
43Create submin environment
44=========================
45
46Multiple submin installations can co-exist on the same server. Therefore, for
47each installation, an environment must be created. All data (repositories,
48configuration, etc) are located in one directory, for example /var/lib/submin.
49
50To create a submin environment, follow instructions after executing:
51
52    submin2-admin /var/lib/submin initenv your@email.address
53
54For help on submin-admin, execute the following command:
55
56    submin2-admin /var/lib/submin help
57    submin2-admin /var/lib/submin help <subcommand>
58
59
60Git support (optional)
61======================
62
63Git support requires a special user to be created and some additional settings.
64Run the following command as root and follow the instructions:
65
66    submin2-admin /var/lib/submin git init
67
68
69Configure Webserver
70===================
71
72Submin2 can create all kinds of configs for you, for both apache and nginx.
73If you only need git you can install nginx, otherwise you need to install
74Apache.
75
76For advanced usage, you can mix Apache and NGINX config!
77
78
79Configure Apache
80----------------
81
82After running initenv above, the apache config files are created. If you want
83to create them again for any reason, run the following command:
84
85    submin2-admin /var/lib/submin apacheconf create all
86
87Now to activate the submin2 website, the configuration should be included into
88Apache2. To use for example CGI and SVN, execute the following commands as
89root (on Debian systems with Apache <2.4):
90
91    ln -s /var/lib/submin/conf/apache-webui-cgi.conf /etc/apache2/conf.d/
92    ln -s /var/lib/submin/conf/apache-svn.conf /etc/apache2/conf.d/
93
94For Debian systems with Apache 2.4+, link the 2.4 versions:
95
96    ln -s /var/lib/submin/conf/apache-2.4-webui-cgi.conf /etc/apache2/conf-available/
97    ln -s /var/lib/submin/conf/apache-2.4-svn.conf /etc/apache2/conf-available/
98    a2enconf apache-2.4-webui-cgi.conf
99    a2enconf apache-2.4-svn.conf
100
101Now restart your webserver to activate the new settings.
102
103    apachectl restart
104
105
106Configure NGINX
107---------------
108
109To generate NGINX config files, run the following command:
110
111    submin2-admin /var/lib/submin nginxconf create all
112
113To activate submin2 in nginx, see instructions in the generated nginx config
114file /var/lib/submin/conf/nginx-webui-wsgi.conf
115
116
117Login to your Submin2 website
118=============================
119
120The email-address you have provided with the 'initenv' command above has
121received a password reset email. Read your email and click the link. You will
122get another email with the password. You can use this to login.
123
124If you did not receive an e-mail, it could be that your server could not
125send it, or that the mail was blocked somewhere. Please run diagnostics:
126
127    submin2-admin /var/lib/submin diagnostics email
128
129If you followed the steps there and you still can't get it to work, please
130make sure you can send emails from the server (for example, test with 'mail'
131on the command line) and then use the 'forgot password' functionality to
132request a password (for the user 'admin').
133
134
135Advanced configuration
136======================
137
138For more advanced configuration, see the CONFIGURATION file included in
139the source code. To find an online version, please see:
140
141https://ssl.supermind.nl/collab/projects/submin/browser/CONFIGURATION
142
143
144Troubleshooting
145===============
146To find the common misconfiguration problems, Submin offers diagnostics. There
147is a web-ui version and a command-line version. The web-ui version can be
148found in the sidebar under 'SYSTEM', the command-line version can be run as:
149
150    submin2-admin /var/lib/submin diagnostics
151
152For more information, see the help of diagnostics ('help diagnostics' instead
153of 'diagnostics).
154
155
156Final touches
157=============
158
159Be sure to check the Diagnostics page after logging in as admin, it will help
160with fine-tuning your configuration for your installation.
161
162With new submin versions, sometimes new checks are added on this page, so be
163sure to check back here after upgrading submin.
164
165
166Happy subminning :)
Note: See TracBrowser for help on using the repository browser.