diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst index 008554b147..e1f3029419 100644 --- a/docs/intro/installation.rst +++ b/docs/intro/installation.rst @@ -2,14 +2,90 @@ Installation ============ -Local or managed server ------------------------ +Automatic install using included fabfile +---------------------------------------- +A Fabric_ file is included to help users not very familiar with Ubuntu_, +Python_ and Django_ install **Mayan EDMS**, or for system administrators +looking to automate the install whether in a local or remote system. + +To bootstrap **Mayan EDMS** via the fabfile without having to clone the +entire repository, run the following command, replacing the part that +reads: with your current MySQL root password +or the MySQL root password you plan to assign to it, during the MySQL +installation when executing the fabfile. + +* Debian or Ubuntu:: + + $ cd /tmp && sudo apt-get install -y fabric wget tar gzip && wget https://raw.github.com/rosarior/mayan/contrib/fabfile.tar.gz -O - | tar -xvzf - && echo "database_manager_admin_password=" > ~/.fabricrc && fab -H localhost install + +* Fedora:: + + $ cd /tmp && sudo yum install -y fabric wget tar gzip && wget https://raw.github.com/rosarior/mayan/contrib/fabfile.tar.gz -O - | tar -xvzf - && echo "database_manager_admin_password=" > ~/.fabricrc && fab -H localhost install + + +The ``fabfile`` also supports deploying to more than one server whether +the they same configuration or not, via a ``server_config.json`` file. +The fabfile also supports YAML server configuration +files but requires installing ``pyyaml`` via ``pip``, ``python-yaml`` +via ``apt`` (Debian_, Ubuntu_) or ``PyYAML`` via ``yum`` (Fedora_) + +A sample ``server_config.yaml`` would be as follows:: + + debian_server: + host: 192.168.1.1 + database_manager_admin_password: my_debian_mysql_pa$$word + drop_database: True + os: debian + ubuntu_server: + host: 192.168.1.2 + database_manager_admin_password: my_ubuntu_mysql_pa$$word + drop_database: True + os: ubuntu + database_username: mayan_release_12 + database_name: mayan_release_12 + all_servers: [debian_server, ubuntu_server] + +To install **Mayan EDMS** to these servers the ``fabfile`` should be called in the following manner:: + + $ fab servers:debian_server install + +or:: + + $ fab servers:ubuntu_server,debian_server install + +or:: + + $ fab servers:all_servers install + + +Configuration options for the ``fabfile``: + +* ``host`` Hostname or address of the host to which to install **Mayan EDMS**. Required setting. +* ``os`` Operating system of the target host. Options: ubuntu, debian, fedora. default: ubuntu +* ``install_path`` Installation path. Default: /usr/share +* ``virtualenv_name`` Name of the directory that will house the virtualenv under the ``install_path``. Default: mayan +* ``repository_name`` Name of the directory where the repository will be clone under the ``virtualenv_name`` directory. Default: mayan +* ``database_manager`` Database manager to use. Options: mysql. Default: mysql +* ``database_username`` Username that will be created and used to access the database. Default: mayan +* ``database_password`` Password of the database user account. Default: random autogenerated password +* ``database_host`` Address of the database manager host. Default: 127.0.0.1 +* ``drop_database`` Weather or not to drop the database when uninstalling **Mayan EDMS** via the fabfile. Default: False +* ``database_manager_admin_password`` Administrator password of the database manager, only used to create the **Mayan EDMS** database and user. Required setting. +* ``database_name`` Name of the **Mayan EDMS** database. Default: mayan +* ``webserver`` Web server that will be install and configure to server **Mayan EDMS**. Options: apache. Default: apache + + +Only the options: ``host``, ``os`` and ``database_manager_admin_password`` should be required for most installations. + + +Local or managed Ubuntu or Debian server +---------------------------------------- **Mayan EDMS** should be deployed_ like any other Django_ project and preferably using virtualenv_. If using a Debian_ or Ubuntu_ based Linux distribution getting the executable requirements is as easy as:: - $ apt-get install tesseract-ocr unpaper python-virtualenv ghostscript libjpeg-dev libpng-dev poppler-utils -y + $ sudo apt-get install python-dev gcc tesseract-ocr unpaper python-virtualenv ghostscript libjpeg-dev libpng-dev poppler-utils -y To initialize a ``virtualenv`` to deploy the project do:: @@ -34,22 +110,18 @@ To install the python dependencies ``easy_install`` can be used, however for eas Create the database that will hold the data. Install any corresponding python database drivers. Update the settings.py file with you database settings. If using the ``MySQL`` database manager, use the following commands:: - $ apt-get install python-dev libmysqlclient-dev gcc -y + $ sudo apt-get install libmysqlclient-dev -y $ pip install MySQL-python -If using PostgreSQL, enter the following:: +If using ``PostgreSQL``, enter the following:: - $ apt-get install python-dev libpq-dev gcc-y - $ pip install pip install psycopg2 + $ sudo apt-get install libpq-dev -y + $ pip install psycopg2 Populate the database with the project's schema doing:: $ ./manage.py syncdb --migrate -Collect the static files of the project into the ``static`` folder for serving via a webserver:: - - $ ./manage.py collectstatic - To test your installation, create a file called settings_local.py with the following content:: DEBUG=True @@ -59,7 +131,96 @@ Execute Django’s development server using the ``runserver`` command to launch $ ./manager.py runserver -Point your browser to http://127:0.0.1:8000, if everything was installed correctly you should see the login screen. After making sure everything is running correctly, stop the runserver command, delete the settings_local.py and deploy Mayan EDMS using the webserver of your preference. If your are using Apache_, a sample site file is included under the contrib directory. +Point your browser to http://127:0.0.1:8000, if everything was installed +correctly you should see the login screen. After making sure everything +is running correctly, stop the runserver command and delete the settings_local.py. +Deploy **Mayan EDMS** using the webserver of your preference. If your are +using Apache_, a sample site file is included under the contrib directory. + +Before finally deploying to your favorite webserver don't forget to collect the +static files of the project into the ``static`` folder for serving via a webserver:: + + $ ./manage.py collectstatic + + + +Local or managed Fedora server +------------------------------ + +**Mayan EDMS** should be deployed_ like any other Django_ project and preferably using virtualenv_. + +If using a Fedora_ based Linux distribution getting the executable requirements is as easy as:: + + $ sudo yum install -y git gcc tesseract unpaper python-virtualenv ghostscript libjpeg-turbo-devel libpng-devel poppler-util python-devel + +To initialize a ``virtualenv`` to deploy the project do:: + + $ virtualenv --no-site-packages mayan + +Download_ and decompress the latest version of **Mayan EDMS**:: + + $ cd mayan + $ tar -xvzf mayan.tar.gz + +Or clone the latest development version straight from github:: + + $ cd mayan + $ git clone git://github.com/rosarior/mayan.git + +To install the python dependencies ``easy_install`` can be used, however for easier retrieval a production dependencies file is included, to use it execute:: + + $ cd mayan + $ source ../bin/activate + $ pip install -r requirements/production.txt + +Create the database that will hold the data. Install any corresponding python database drivers. Update the settings.py file with you database settings. +If using the ``MySQL`` database manager, use the following commands:: + + $ sudo yum install -y mysql-devel + $ pip install MySQL-python + +If using ``PostgreSQL``, enter the following:: + + $ sudo yum install -y postgresql-devel + $ pip install psycopg2 + +Populate the database with the project's schema doing:: + + $ ./manage.py syncdb --migrate + +To test your installation, create a file called settings_local.py with the following content:: + + DEBUG=True + DEVELOPMENT=True + +Execute Django’s development server using the ``runserver`` command to launch a local instance of Mayan EDMS:: + + $ ./manager.py runserver + +Point your browser to http://127:0.0.1:8000, if everything was installed +correctly you should see the login screen. After making sure everything +is running correctly, stop the runserver command and delete the settings_local.py. +Deploy **Mayan EDMS** using the webserver of your preference. If your are +using Apache_, a sample site file is included under the contrib directory. + +Before finally deploying to your favorite webserver don't forget to collect the +static files of the project into the ``static`` folder for serving via a webserver:: + + $ ./manage.py collectstatic + + +Cloud install +------------- +SaaS provied Appsembler_ has started providing a "1-click install" cloud +offering of **Mayan EDMS**. Go to their website and click on apps to start +your trial period of **Mayan EDMS** on the cloud. + + +DjangoZoom +---------- +For instructions on how to deploy **Mayan EDMS** on DjangoZoom, watch the screencast: + +"Deploying Mayan EDMS on DjangoZoom.net" available on Youtube_ Webfaction @@ -171,11 +332,6 @@ To install **Mayan EDMS** on Webfaction_, follow these steps: apache2/bin/restart -DjangoZoom ----------- -For instructions on how to deploy **Mayan EDMS** on DjangoZoom, watch the screencast: - -"Deploying Mayan EDMS on DjangoZoom.net" available on Youtube_ .. _`vendor lock-in`: https://secure.wikimedia.org/wikipedia/en/wiki/Vendor_lock-in @@ -196,3 +352,6 @@ For instructions on how to deploy **Mayan EDMS** on DjangoZoom, watch the screen .. _deployed: https://docs.djangoproject.com/en/1.3/howto/deployment/ .. _virtualenv: http://www.virtualenv.org/en/latest/index.html .. _`Reducing mod_wsgi Memory Consumption`: http://docs.webfaction.com/software/mod-wsgi.html#mod-wsgi-reducing-memory-consumption +.. _Fedora: http://fedoraproject.org/ +.. _Fabric: http://docs.fabfile.org/ +.. _Appsembler: http://appsembler.com/