summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMikaël Ates <mikael.ates@gmail.com>2012-05-11 15:32:14 (GMT)
committerMikaël Ates <mikael.ates@gmail.com>2012-05-11 15:32:14 (GMT)
commit5446cc9071c0a9ce70cbccedc1b5e865348e6f21 (patch)
tree778cce9341734f5829f4ee74b52ef19889b38422 /doc
parentb31952b15186629e638a8b4562567170ce7ce398 (diff)
downloadauthentic-5446cc9071c0a9ce70cbccedc1b5e865348e6f21.zip
authentic-5446cc9071c0a9ce70cbccedc1b5e865348e6f21.tar.gz
authentic-5446cc9071c0a9ce70cbccedc1b5e865348e6f21.tar.bz2
[doc] Update installation part of the documentation.
The documentation should be clearer about the installation of Authentic 2, taking in account that the setup script now manages dependencies. The documentation also contains a new part about the deployments in production and the use of collectstatic.
Diffstat (limited to 'doc')
-rw-r--r--doc/change_db.rst21
-rw-r--r--doc/download.rst13
-rw-r--r--doc/index.rst8
-rw-r--r--doc/installation.rst272
-rw-r--r--doc/production.rst59
-rw-r--r--doc/upgrading.rst20
6 files changed, 309 insertions, 84 deletions
diff --git a/doc/change_db.rst b/doc/change_db.rst
new file mode 100644
index 0000000..bfbaa92
--- /dev/null
+++ b/doc/change_db.rst
@@ -0,0 +1,21 @@
+.. _change_db:
+
+===============================
+Specifying a different database
+===============================
+
+This is done by modifying the DATABASES dictionary in your local_settings.py
+file (create it in Authentic project directory); for example::
+
+ DATABASES['default'] = {
+ 'ENGINE': 'django.db.backends.postgresql',
+ 'NAME': 'authentic',
+ 'USER': 'admindb',
+ 'PASSWORD': 'foobar',
+ 'HOST': 'db.example.com',
+ 'PORT': '', # empty string means default value
+ }
+
+You should refer to the Django documentation on databases settings at
+http://docs.djangoproject.com/en/dev/ref/settings/#databases for all
+the details.
diff --git a/doc/download.rst b/doc/download.rst
deleted file mode 100644
index a0a8ada..0000000
--- a/doc/download.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _download:
-
-========
-Download
-========
-
-1. Obtain the last archive on Pypi:
-
- http://pypi.python.org/pypi/authentic2/2.0.1
-
-2. Obtain the last stable source on the Git repository:
-
- git clone http://repos.entrouvert.org/authentic.git
diff --git a/doc/index.rst b/doc/index.rst
index a283ec0..4cba583 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -33,10 +33,14 @@ Documentation content
features
- download
-
installation
+ production
+
+ upgrading
+
+ change_db
+
settings
auth_ldap
diff --git a/doc/installation.rst b/doc/installation.rst
index 40d19cc..9dcd201 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -4,124 +4,258 @@
Installation
============
-Dependencies
-------------
+Authentic 2 installation script handles all the dependencies, except Lasso,
+relying on the Setuptools and the pypi repository.
-You must install the following packages to use Authentic
+To run Authentic 2 you need to install Lasso >=2.3.6. You can obtain Lasso
+from:
-- Python Lasso binding 2.3.6:
+- From sources: http://lasso.entrouvert.org/download
+- Debian based distribution: http://deb.entrouvert.org/
- From sources: http://lasso.entrouvert.org/download
- Debian based distribution: http://deb.entrouvert.org/
+The other Authentic 2 dependencies are:
-- Django 1.4:
+- django >= 1.3
+- django-profiles >= 0.2
+- south >= 0.7.3
+- django-authopenid >= 0.9.6
+- django-debug-toolbar >= 0.9.0
- From sources: http://www.djangoproject.com/download/1.4/tarball/
+Their management depends on how you install Authentic 2:
-- Django-authopenid 0.9.6:
+- You can :ref:`install-pypi-ref`
+- You can :ref:`obtain-pypi-ref`
+- You can :ref:`obtain-git-ref`
- From sources: http://bitbucket.org/benoitc/django-authopenid/downloads
+Lasso installation mock-up
+--------------------------
-- Django-south 0.7.3:
+Please see the Lasso website for installation details. This is a quick
+installation example.
- From sources:: http://south.aeracode.org/docs/installation.html
+Install the following Lasso dependencies:
-- Django-profiles 0.2:
+- autoconf
+- automake
+- autotools-dev
+- libtool
+- gtk-doc-tools
+- zlib1g-dev
+- libglib2.0-dev
+- openssl-dev
+- libxml2-dev
+- libxmlsec1-dev
+- python2.6-dev
+- python-setuptools
- From sources:: http://pypi.python.org/pypi/django-profiles
+Obtain Lasso::
-You install all the django libraries quickly using pip::
+ $wget https://dev.entrouvert.org/lasso/lasso-2.3.6.tar.gz
+ $tar xzvf lasso-2.3.6.tar.gz
+ $cd lasso-2.3.6
+ $./autogen.sh
- pip install django django-profiles django-authopenid south
+Be sure that the Python bindings is selected as follows::
-or easy_install::
+ =============
+ Configuration
+ =============
+
+ Main
+ ----
+
+ Compiler: gcc
+ CFLAGS:
+ Install prefix: /usr/local
+ Debugging: no
+ Experimental ID-WSF: no
+
+ Optionals builds
+ ----------------
+
+ Available languages: java(4.6.1) python(2.7) perl(5.12.4)
+
+ Java binding: yes
+ Perl binding: yes
+ PHP 5 binding: no
+ Python binding: yes
+
+ C API references: yes
+ Tests suite: no
+
+
+ Now type 'make install' to install lasso.
+
+As indicated, build and install::
- easy_install django django-profiles django-authopenid south
+ $make install
+ $ldconfig
-**Dependencies in DEBUG mode (Default mode)**
+Set the lasso python binding in you python path, e.g.::
-- Django Debug Toolbar:
+ $export PYTHONPATH="$PYTHONPATH:/usr/local/lib/python2.6/site-packages"
- From sources:: https://github.com/django-debug-toolbar/django-debug-toolbar
+Test trying to import Lasso::
+
+ $python
+ >>> import lasso
+
+.. _install-pypi-ref:
+
+Install Authentic directly from pypi
+------------------------------------
Using pip::
- pip install django-debug-toolbar
+ pip install authentic2
+
+or easy_install::
+
+ easy_install authentic2
+
+You can now run Authentic from the installation directory, e.g.::
+
+ python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py syncdb --migrate
+ python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py runserver
+
+You should see the following output::
+
+ Validating models...
+ 0 errors found
+
+ Django version 1.4, using settings 'authentic.settings'
+ Development server is running at http://127.0.0.1:8000/
+ Quit the server with CONTROL-C.
+
+ You can access the running application on http://127.0.0.1:8000/
+
+.. _obtain-pypi-ref:
+
+Obtain the last package archive from pypi
+-----------------------------------------
+
+Download the archive on http://pypi.python.org/pypi/authentic2/.
+
+Then, you can install it directly from the archive using pip::
+
+ pip install authentic2-x.z.y.tar.gz
or easy_install::
- easy_install django-debug-toolbar
+ easy_install authentic2-x.z.y.tar.gz
+
+You can now run Authentic from the installation directory, e.g.::
+
+ python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py syncdb --migrate
+ python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py runserver
+
+You should see the following output::
+
+ Validating models...
+ 0 errors found
+
+ Django version 1.4, using settings 'authentic.settings'
+ Development server is running at http://127.0.0.1:8000/
+ Quit the server with CONTROL-C.
+
+ You can access the running application on http://127.0.0.1:8000/
+
+You may not want to install the authentic2 package or you may want to manage the dependencies
+_____________________________________________________________________________________________
+
+Then, extract the archive::
+
+ tar xzvf authentic2-x.z.y.tar.gz
+ cd authentic2-x.z.y
-Quick Start
------------
+You can now install the dependencies by hands or use pypi to install them as
+follows, either::
-Then launch the following commands::
+ pip install django django-profiles south django-authopenid django-debug-toolbar
- python manage.py syncdb --migrate
- python manage.py collectstatic # Not necessary in DEBUG mode
- python manage.py runserver
+or using the dependencies version requirements::
+
+ python setup.py egg_info
+ pip install -r authentic2.egg-info/requires.txt
+
+Then run Authentic from the extracted directory::
+
+ python authentic2/manage.py syncdb --migrate
+ python authentic2/manage.py runserver
You should see the following output::
Validating models...
0 errors found
- Django version 1.2, using settings 'authentic.settings'
+ Django version 1.4, using settings 'authentic.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
You can access the running application on http://127.0.0.1:8000/
+.. _obtain-git-ref:
+
+Obtain the last sources from the Git repository
+-----------------------------------------------
+
+Clone the repository::
+
+ git clone http://repos.entrouvert.org/authentic.git
+
+Then, you can install it directly using pip::
+
+ pip install ./authentic
+
+or easy_install::
+
+ easy_install ./authentic
+
+You can now run Authentic from the installation directory, e.g.::
-Specifying a different database
--------------------------------
+ python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py syncdb --migrate
+ python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py runserver
+
+You should see the following output::
-This is done by modifying the DATABASES dictionary in your local_settings.py
-file (create it in Authentic project directory); for example::
+ Validating models...
+ 0 errors found
- DATABASES['default'] = {
- 'ENGINE': 'django.db.backends.postgresql',
- 'NAME': 'authentic',
- 'USER': 'admindb',
- 'PASSWORD': 'foobar',
- 'HOST': 'db.example.com',
- 'PORT': '', # empty string means default value
- }
+ Django version 1.4, using settings 'authentic.settings'
+ Development server is running at http://127.0.0.1:8000/
+ Quit the server with CONTROL-C.
-You should refer to the Django documentation on databases settings at
-http://docs.djangoproject.com/en/dev/ref/settings/#databases for all
-the details.
+ You can access the running application on http://127.0.0.1:8000/
-How to upgrade to a new version of authentic ?
-----------------------------------------------
+You may not want to install the authentic2 package or you may want to manage the dependencies
+_____________________________________________________________________________________________
-Authentic stores all its data in a relational database as specified in its
-settings.py or local_settings.py file. So in order to upgrade to a new version
-of authentic you have to update your database schema using the
-migration command — you will need to have installed the dependency
-django-south, see the beginning of this README file.::
+Then, extract the archive::
- python ./manage.py migrate
+ cd authentic
-Then you will need to create new tables if there are.::
+You can now install the dependencies by hands or use pypi to install them as
+follows, either::
- python ./manage.py syncdb
+ pip install django django-profiles south django-authopenid django-debug-toolbar
-DEBUG Mode by default, static files and the Django debug toolbar dependency ?
------------------------------------------------------------------------------
+or using the dependencies version requirements::
-By default, Authentic 2 is in the DEBUG mode. As a matter of fact, static
-files are only served by the Django development server when the project is
-run in the DEBUG mode.
+ python setup.py egg_info
+ pip install -r authentic2.egg-info/requires.txt
-Then, we made this temporary choice (DEBUG mode by default) because most
-of the users will begin with Authentic 2 using the Django development server
-and we want to avoid that people have a bad first impression because static
-files would not be served.
+Then run Authentic::
-In production, the Django development server should not be used and a
-dedicated server should be used to serve the static files.
+ python authentic2/manage.py syncdb --migrate
+ python authentic2/manage.py runserver
-In the DEBUG mode, the Django Debug Toolbar is used. Then, by default,
-Authentic 2 is also dependant of this module. Find more information on
-https://github.com/django-debug-toolbar/django-debug-toolbar#readme.
+You should see the following output::
+
+ Validating models...
+ 0 errors found
+
+ Django version 1.4, using settings 'authentic.settings'
+ Development server is running at http://127.0.0.1:8000/
+ Quit the server with CONTROL-C.
+
+ You can access the running application on http://127.0.0.1:8000/
diff --git a/doc/production.rst b/doc/production.rst
new file mode 100644
index 0000000..5ee9467
--- /dev/null
+++ b/doc/production.rst
@@ -0,0 +1,59 @@
+.. _production:
+
+================================
+Deploy Authentic 2 in production
+================================
+
+DEBUG Mode by default, static files and the Django debug toolbar dependency ?
+-----------------------------------------------------------------------------
+
+By default, Authentic 2 is in the DEBUG mode. We made this default choice
+because most of the Authentic 2's users will begin with Authentic 2 using
+the Django development server (runserver command) and we want to avoid them
+a bad first impression because static files would not be served. As a matter
+of fact, static files are served by the Django development server only when
+the project is run in the DEBUG mode.
+
+In the DEBUG mode, the Django debug toolbar is used what adds a dependency.
+
+In production, the Django development server should not be used to serve
+Authentic 2 and a dedicated server should also be used to serve the static
+files.
+
+Set Authentic into the no DEBUG Mode
+------------------------------------
+
+It is enough to edit authentic2/settings.py and set::
+
+ DEBUG = False
+
+From then on the django-debug-toolbar package is not necessary anymore.
+
+Use dedicated HTTP servers and serve static files
+-------------------------------------------------
+
+The best is to use a server dedicated to serve the Django applications and a
+different server to serve the static files.
+
+You could for instance use apache with mod_wsgi to serve Authentic 2. You will
+find configuration file examples in the debian directory of the Authentic 2
+sources.
+
+Then you may want to use nginx to serve the static files.
+
+First you need to collect the Authentic 2 static files. The static files are
+collected using the collectstatic command that is configured in the
+settings.py.
+
+By default, running collectstatic will create a static directory in the parent
+directory of the authentic2 directory::
+
+ $python authentic2/manage.py collectstatic
+
+That static directory will contain all the static files of Authentic 2.
+
+If you want to change the path of the static directory you can edit
+STATIC_ROOT of the settings file.
+
+See https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ for more
+information about collectstatic.
diff --git a/doc/upgrading.rst b/doc/upgrading.rst
new file mode 100644
index 0000000..1be444d
--- /dev/null
+++ b/doc/upgrading.rst
@@ -0,0 +1,20 @@
+.. _upgrading:
+
+=========
+Upgrading
+=========
+
+How to upgrade to a new version of authentic ?
+----------------------------------------------
+
+Authentic stores all its data in a relational database as specified in its
+settings.py or local_settings.py file. So in order to upgrade to a new version
+of authentic you have to update your database schema using the
+migration command — you will need to have installed the dependency
+django-south, see the beginning of this README file.::
+
+ python ./manage.py migrate
+
+Then you will need to create new tables if there are.::
+
+ python ./manage.py syncdb