diff --git a/docs/conf.py b/docs/conf.py index e41e99ca1a49ee564cb680a9e5ea15184dcfb1a9..9621b88b9a4a4059f3bf7e2e0b1053772bccef60 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -113,7 +113,7 @@ html_theme = 'alabaster' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['../memopol_env/local/lib/python2.7/site-packages'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/docs/development.rst b/docs/development.rst index fe639602d028cc861323eca1f0e594232343800e..b64c22ecd0b4b5394da930f43c18e65c176fde3d 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -5,8 +5,47 @@ This tutorial drives through a local installation of the project for development on Linux. It requires git, a fairly recent version of python2, virtualenv and PostgreSQL. -Quickstart -========== +Setup the database +================== + +Memopol requires PostgreSQL 9.1 or higher. It used to run with SQLite, too, but +that is no longer the case. It is better to install and configure you're local +PostgreSQL server before starting to install Memopol. + +On Debian +--------- + +To setup you're PostgreSQL database on a debian stable distribution, you can use +the package manager apt:: + + $ apt install postgresql postgresql-server-dev-9.X + +Then you need to create the 'memopol' user and the 'memopol' database:: + + # To have a root access on Postgres, you need to connect as user 'postgres' + $ su - postgres + $ psql -c "create user memopol with password 'memopol';" + $ psql -c "alter role memopol with createdb;" + $ psql -c "create database memopol with owner memopol;" + $ exit + +You're database is now setup for Memopol. You can now launch the 'quickstart.sh' +script to automatically install all the components or do it manually. + +In General +---------- + +Make sure the corresponding user and database exist on your system; the user +will need the 'createdb' permission in order to be able to run tests. To create +them, you may use the following commands:: + + $ psql -c "create user memopol with password 'memopol';" -U postgres + $ psql -c "alter role memopol with createdb;" -U postgres + $ psql -c "create database memopol with owner memopol;" -U postgres + + +Automatic Install +================= There is a quickstart script used and tested manually by some of the developers. Feel free to try it, but don't worry if it doesn't work for you @@ -19,14 +58,42 @@ Here's how to try it:: $ cd memopol $ source bin/quickstart.sh +At this point, you should now run the development server and access to Memopol:: + + $ memopol runserver + If you want more control or if it doesn't work for you, then follow the steps below or have a look at what the quickstart script does. -.. note:: - If you are using python 3 on your system, the quickstart script will install - the virtualenv with this version. You'll need to remove the directory - 'memopol_env' and recreate it with the python version 2.7 in parameter - 'virtualenv -p /usr/bin/python2.7 memopol_env' +Development helper +=================== + +You can run the script 'bin/dev.sh' to automaticaly setup some aliases. It works +only with Bash and Zsh. + +The script build a custom file named '.memopol.alias' at the root of the project +containing all the aliases for memopol. All the path to the project are build +automatically. A single line is added to your '$HOME/.bashrc' or '$HOME/.zshrc' +to source the aliases. + +After execute 'bin/dev.sh' you should close the current terminal and open +another one to have access to the aliases. + +There is a quick list of available aliases:: + + memopol-code : Go into the repository and activate virtualenv and + set Django in debug mode + memopol-launch : Run the development server echo + memopol-update-all : Get all the production data + memopol-refresh-scores : Refresh all scores + +.. warning:: If you are using multiple setup of Memopol, it is not recommended to + use this script. + +If you need to change the location of the project, you should remove this line +from your .bashrc or .zshrc:: + + source $PATH_TO_THE_PROJECT/.memopol.alias Make a virtual environment ========================== @@ -107,31 +174,11 @@ Activate ``DJANGO_DEBUG`` ========================= ``DEBUG`` is disabled by default, the development server -won't run properly by default thnen, to enable it export +won't run properly by default then, to enable it export the ``DJANGO_DEBUG`` variable in the current shell:: $ export DJANGO_DEBUG=True -Setup the database -================== - -Memopol requires PostgreSQL 9.1 or higher. It used to run with SQLite, too, but -that is no longer the case. Memopol uses the following environment variables -for database access: - -* ``MEMOPOL_DB_NAME`` (defaults to 'memopol') -* ``MEMOPOL_DB_USER`` (defaults to 'memopol') -* ``MEMOPOL_DB_PASSWORD`` (defaults to 'memopol') -* ``MEMOPOL_DB_HOST`` (defaults to 'localhost') -* ``MEMOPOL_DB_PORT`` (defaults to '5432') - -Make sure the corresponding user and database exist on your system; the user -will need the 'createdb' permission in order to be able to run tests. To create -them, you may use the following commands:: - - $ psql -c "create user memopol with password 'memopol';" -U postgres - $ psql -c "alter role memopol with createdb;" -U postgres - $ psql -c "create database memopol with owner memopol;" -U postgres Database migrations =================== diff --git a/docs/index.rst b/docs/index.rst index 29ffd717aa78fcae3fa036665587d657435256d9..569ee2786998b95759abe127cb5e8e441ef37d69 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Contents: api development hacker + setup_solr Indices and tables ================== @@ -26,4 +27,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/setup_solr.rst b/docs/setup_solr.rst new file mode 100644 index 0000000000000000000000000000000000000000..e5b98d86666510b7dd26af028c784723f144f1f9 --- /dev/null +++ b/docs/setup_solr.rst @@ -0,0 +1,80 @@ +Setup Solr with Memopol +======================= + +Solr is used to perform search in the data. Currently, it is used only for +reprensatative search autocomplete. + +This howto will be based on the current stable version of Debian (jessie). + +Installation on Debian Stable +----------------------------- + +Solr is in the official repository of debian, you can install it launching:: + + # apt install solr-tomcat/stable + Package: solr-tomcat + Source: lucene-solr + Version: 3.6.2+dfsg-5 + Installed-Size: 65,5 kB + Maintainer: Debian Java Maintainers + Depends: solr-common (= 3.6.2+dfsg-5), tomcat7 + Conflicts: solr-jetty, solr-tomcat6 + Homepage: http://lucene.apache.org + Section: java + Priority: optional + Download-Size: 8 598 B + APT-Sources: http://ftp.fr.debian.org/debian/ jessie/main amd64 Packages + Description: Enterprise search server based on Lucene3 - Tomcat integration + Solr is an open source enterprise search server based on the Lucene + Java search library, with XML/HTTP and JSON APIs, hit highlighting, + faceted search, caching, replication, and a web administration + interface. It runs in a Java servlet container such as Tomcat. + . + This package provides the Tomcat integration files for Solr. + + +By default, the solr server is listen on localhost:8080. Memopol is configured +to use this addess by default, in production. If you install a newer version of +Solr (6.5.1 is the latest release), you should update the settings.py:: + + HAYSTACK_CONNECTIONS = { + 'default': { + 'ENGINE': 'haystack.backends.solr_backend.SolrEngine', + 'URL': 'http://127.0.0.1:8080/solr', + }, + } + +Configure Solr +--------------- + +You can use the default Solr configuration to use it, You just need to generate +the schema.xml file and copy it in `/etc/solr/`. To generate the schema.xml +file:: + + $ memopol build_solr_schema > schmema.xml + + ## Copy the schema.xml file into /etc/solr/conf + $ sudo cp schema.xml /etc/solr/conf/ + + ## Restart tomcat + $ sudo /etc/init.d/tomcat7 restart + +Last step, you need to build the index by using:: + + $ memopol rebuild_index + +The solr is now setup and production ready. + +Populate data in Solr +--------------------- + +Django-haystack plugin offers two ways to populate data. The first way is by +using a cron job to update the index, the other way is to use `Dango signals to +update / delete datas `_. + +For now, Haystack is not configured to be used with Django signals. It is +necessary to add a cron job to update the index :: + + $ memopol update_index + +`More informations about cron with Solr `_ diff --git a/setup.py b/setup.py index 7e7852fd9109d871a7f89c9203c27d2864a3763f..da4413b023fc8f8161a99fcb8eb6103aed24cbbf 100644 --- a/setup.py +++ b/setup.py @@ -30,6 +30,7 @@ setup(name='political-memory', 'pytz', # Always use up-to-date TZ data 'django-suit>=0.2,<0.3', 'psycopg2>=2,<3', + 'alabaster==0.7.10', ], extras_require={ # Full version hardcode for testing dependencies so that