Merge branch 'master' of https://code.grnet.gr/git/pithos
[pithos] / docs / source / adminguide.rst
1 Administrator Guide
2 ===================
3
4 Simple Setup
5 ------------
6
7 Assuming a clean debian squeeze (stable) installation, use the following steps to run the software.
8
9 Install packages::
10
11   apt-get install git python-django python-setuptools python-sphinx
12   apt-get install python-sqlalchemy python-mysqldb python-psycopg2
13   apt-get install apache2 libapache2-mod-wsgi
14
15 Get the source::
16
17   cd /
18   git clone https://code.grnet.gr/git/pithos
19
20 Setup the files (choose where to store data in ``settings.py`` and change ``SECRET_KEY``)::
21
22   cd /pithos/pithos
23   cp settings.py.dist settings.py
24   python manage.py syncdb
25   cd /pithos
26   python setup.py build_sphinx
27
28 Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directive)::
29
30   <VirtualHost *:80>
31     ServerAdmin webmaster@pithos.dev.grnet.gr
32     ServerName pithos.dev.grnet.gr
33
34     DocumentRoot /pithos/htdocs
35     Alias /ui "/var/www/pithos_web_client"
36     Alias /docs "/pithos/docs/build/html"
37
38     <Directory />
39         Options Indexes FollowSymLinks
40         AllowOverride None
41         Order allow,deny
42         Allow from all
43     </Directory>
44
45     RewriteEngine On
46     RewriteRule ^/v(.*) /api/v$1 [PT]
47     RewriteRule ^/public(.*) /api/public$1 [PT]
48     RewriteRule ^/login(.*) https://%{HTTP_HOST}%{REQUEST_URI}
49     RewriteRule ^/admin(.*) https://%{HTTP_HOST}%{REQUEST_URI}
50
51     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
52     # WSGIDaemonProcess pithos
53     # WSGIProcessGroup pithos
54
55     LogLevel warn
56     ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
57     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
58   </VirtualHost>
59
60 Edit ``/etc/apache2/sites-available/pithos-ssl`` (assuming files in ``/etc/ssl/private/pithos.dev.grnet.gr.key`` and ``/etc/ssl/certs/pithos.dev.grnet.gr.crt`` - change the ``ServerName`` directive)::
61
62   <IfModule mod_ssl.c>
63   <VirtualHost _default_:443>
64     ServerAdmin webmaster@pithos.dev.grnet.gr
65     ServerName pithos.dev.grnet.gr
66
67     DocumentRoot /pithos/htdocs
68     Alias /ui "/var/www/pithos_web_client"
69     Alias /docs "/pithos/docs/build/html"
70
71     <Directory />
72         Options Indexes FollowSymLinks
73         AllowOverride None
74         Order allow,deny
75         Allow from all
76     </Directory>
77
78     RewriteEngine On
79     RewriteRule ^/v(.*) /api/v$1 [PT]
80     RewriteRule ^/public(.*) /api/public$1 [PT]
81     RewriteRule ^/login(.*) /api/login$1 [PT]
82     RewriteRule ^/admin(.*) /api/admin$1 [PT]
83
84     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
85     # WSGIDaemonProcess pithos
86     # WSGIProcessGroup pithos
87
88     ShibConfig /etc/shibboleth/shibboleth2.xml
89     Alias      /shibboleth-sp /usr/share/shibboleth 
90
91     <Location /api/login>
92         AuthType shibboleth
93         ShibRequireSession On
94         ShibUseHeaders On
95         require valid-user
96     </Location>
97
98     LogLevel warn
99     ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
100     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
101
102     SSLEngine on
103     SSLCertificateFile    /etc/ssl/certs/pithos.dev.grnet.gr.crt
104     SSLCertificateKeyFile /etc/ssl/private/pithos.dev.grnet.gr.key
105   </VirtualHost>
106   </IfModule>
107
108 Add in ``/etc/apache2/mods-available/wsgi.conf``::
109
110   WSGIChunkedRequest On
111
112 Configure and run apache::
113
114   a2enmod ssl
115   a2enmod rewrite
116   a2dissite default
117   a2ensite pithos
118   a2ensite pithos-ssl
119   mkdir /var/www/pithos
120   mkdir /var/www/pithos_web_client
121   /etc/init.d/apache2 restart
122
123 Useful alias to add in ``~/.bashrc``::
124
125   alias pithos-sync='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
126
127 Shibboleth Setup
128 ----------------
129
130 Install package::
131
132   apt-get install libapache2-mod-shib2
133
134 Setup the files in ``/etc/shibboleth``.
135
136 Add in ``/etc/apache2/sites-available/pithos-ssl``::
137
138         ShibConfig /etc/shibboleth/shibboleth2.xml
139         Alias      /shibboleth-sp /usr/share/shibboleth 
140
141         <Location /api/login>
142                 AuthType shibboleth
143                 ShibRequireSession On
144                 ShibUseHeaders On
145                 require valid-user
146         </Location>
147
148 Configure and run apache::
149
150   a2enmod shib2
151   /etc/init.d/apache2 restart
152   /etc/init.d/shibd restart
153
154 MySQL Setup
155 -----------
156
157 If using MySQL instead of SQLite for the database engine, consider the following.
158
159 Server side::
160
161   apt-get install mysql-server
162
163 Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
164
165 Create database and user::
166
167   CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
168   GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
169   GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
170
171 Client side::
172
173   apt-get install mysql-client
174
175 It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
176
177   [client]
178   user = pithos
179   password = 'password'
180   host = pithos-storage.dev.grnet.gr
181
182   [mysql]
183   database = pithos
184
185 PostgreSQL Setup
186 ----------------
187
188 If using PostgreSQL instead of SQLite for the database engine, consider the following.
189
190 Server side::
191
192   apt-get install postgresql
193
194 Edit ``/etc/postgresql/8.4/main/postgresql.conf`` and ``/etc/postgresql/8.4/main/pg_hba.conf`` to allow network connections and restart the server.
195
196 Create database and user::
197
198   CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
199   CREATE USER pithos WITH PASSWORD 'password';
200   GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
201
202 Client side::
203
204   apt-get install postgresql-client
205
206 It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server::
207
208   pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
209
210 Connect with::
211
212   psql -h pithos-storage.dev.grnet.gr -U pithos
213