diff --git a/doc/install-from-source.rst b/doc/install-from-source.rst index 6d53bd6ab2f..27c98ac1a57 100644 --- a/doc/install-from-source.rst +++ b/doc/install-from-source.rst @@ -12,147 +12,149 @@ There is a page of help for dealing with :doc:`common-error-messages`. For support during installation, please contact `the ckan-dev mailing list `_. -Install the Source ------------------- - -1. Ensure the required packages are installed. - - If you have access to ``apt-get``, you can install these packages as follows: - - :: - - sudo apt-get install mercurial python-dev postgresql libpq-dev - sudo apt-get install libxml2-dev libxslt-dev python-virtualenv - sudo apt-get install wget build-essential git-core subversion - sudo apt-get install solr-jetty openjdk-6-jdk - - Otherwise, you should install these packages from source. - - ===================== =============================================== - Package Description - ===================== =============================================== - mercurial `Source control `_ - python `Python v2.5-2.7 `_ - postgresql `PostgreSQL database `_ - libpq `PostgreSQL library `_ - libxml2 `XML library development files `_ - libxslt `XSLT library development files `_ - virtualenv `Python virtual environments `_ - wget `Command line tool for downloading from the web `_ - build-essential Tools for building source code (or up-to-date Xcode on Mac) - git `Git source control (for getting MarkupSafe src) `_ - subversion `Subversion source control (for pyutilib) `_ - solr `Search engine `_ - jetty `HTTP server `_ (used for Solr) - openjdk-6-jdk `OpenJDK Java library `_ - ===================== =============================================== +1. Ensure the required packages are installed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have access to ``apt-get``, you can install these packages as follows: + +:: + + sudo apt-get install mercurial python-dev postgresql libpq-dev + sudo apt-get install libxml2-dev libxslt-dev python-virtualenv + sudo apt-get install wget build-essential git-core subversion + sudo apt-get install solr-jetty openjdk-6-jdk + +Otherwise, you should install these packages from source. + +===================== =============================================== +Package Description +===================== =============================================== +mercurial `Source control `_ +python `Python v2.5-2.7 `_ +postgresql `PostgreSQL database `_ +libpq `PostgreSQL library `_ +libxml2 `XML library development files `_ +libxslt `XSLT library development files `_ +virtualenv `Python virtual environments `_ +wget `Command line tool for downloading from the web `_ +build-essential Tools for building source code (or up-to-date Xcode on Mac) +git `Git source control (for getting MarkupSafe src) `_ +subversion `Subversion source control (for pyutilib) `_ +solr `Search engine `_ +jetty `HTTP server `_ (used for Solr) +openjdk-6-jdk `OpenJDK Java library `_ +===================== =============================================== - 2. Create a Python virtual environment. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - In your home directory run the command below. It is currently important to - call your virtual environment ``pyenv`` so that the automated deployment tools - work correctly. - - :: - - cd ~ - virtualenv pyenv - - .. tip :: - - If you don't have a ``python-virtualenv`` package in your distribution - you can get a ``virtualenv.py`` script from within the - `virtualenv source distribution `_ - and then run ``python virtualenv.py pyenv`` instead. - - To help with automatically installing CKAN dependencies we use a tool - called ``pip``. Make sure you have activated your environment (see step 3) - and then install it from an activated shell like this: - - :: - - easy_install pip - -3. Activate your virtual environment. +In your home directory run the command below. It is currently important to +call your virtual environment ``pyenv`` so that the automated deployment tools +work correctly. - To work with CKAN it is best to adjust your shell settings so that your - shell uses the virtual environment you just created. You can do this like - so: +:: - :: + cd ~ + virtualenv pyenv - . pyenv/bin/activate +.. tip :: - When your shell is activated you will see the prompt change to something - like this: + If you don't have a ``python-virtualenv`` package in your distribution + you can get a ``virtualenv.py`` script from within the + `virtualenv source distribution `_ + and then run ``python virtualenv.py pyenv`` instead. - :: + To help with automatically installing CKAN dependencies we use a tool + called ``pip``. Make sure you have activated your environment (see step 3) + and then install it from an activated shell like this: - (pyenv)[ckan@host ~/]$ + :: - An activated shell looks in your virtual environment first when choosing - which commands to run. If you enter ``python`` now it will actually - run ``~/pyenv/bin/python``, not the default ``/usr/bin/python`` which is what you want for CKAN. You can install python packages install this new environment and they won't affect the default ``/usr/bin/python``. This is necessary so you can use particular versions of python packages, rather than the ones installed with default paython, and these installs do not affect other python software on your system that may not be compatible with these packages. + easy_install pip -4. Install CKAN code and other required Python packages into the new environment. +3. Activate your virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Choose which version of CKAN to install. Released versions are listed at https://github.com/okfn/ckan - click on the list of tags. For example: ``ckan-1.5`` +To work with CKAN it is best to adjust your shell settings so that your +shell uses the virtual environment you just created. You can do this like +so: - :: +:: - pip install --ignore-installed -e git+https://github.com/okfn/ckan.git@ckan-1.5#egg=ckan + . pyenv/bin/activate - Alternatively, if you are to develop CKAN, then you will probably want to use the latest 'bleeding edge' code. If using this version, we suggest you `check CKAN has passed the automatic tests `_. Here is how to install the latest code:: +When your shell is activated you will see the prompt change to something +like this: - pip install --ignore-installed -e git+https://github.com/okfn/ckan.git#egg=ckan +:: -5. CKAN has a set of dependencies it requires which you should install too. These are listed in three text files: requires/lucid_*.txt, followed by WebOb explicitly. + (pyenv)[ckan@host ~/]$ - First we install two of the three lists of dependencies: +An activated shell looks in your virtual environment first when choosing +which commands to run. If you enter ``python`` now it will actually +run ``~/pyenv/bin/python``, not the default ``/usr/bin/python`` which is what you want for CKAN. You can install python packages install this new environment and they won't affect the default ``/usr/bin/python``. This is necessary so you can use particular versions of python packages, rather than the ones installed with default paython, and these installs do not affect other python software on your system that may not be compatible with these packages. - :: +4. Install CKAN source code +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - pip install --ignore-installed -r pyenv/src/ckan/requires/lucid_missing.txt -r pyenv/src/ckan/requires/lucid_conflict.txt - pip install webob==1.0.8 +Here is how to install the latest code (HEAD on the master branch):: - The ``--ignore-installed`` option ensures ``pip`` installs software into - this virtual environment even if it is already present on the system. + pip install --ignore-installed -e git+https://github.com/okfn/ckan.git#egg=ckan - WebOb has to be installed explicitly afterwards because by installing pylons with `--ignore-installed` you end up with a newer (incompatible) version than the one that Pylons and CKAN need. +If you want to install a specific version, e.g. for v1.5.1:: - Now to install the remaining dependencies in requires/lucid_present.txt and you are using Ubuntu Lucid 10.04 you can install the system versions:: + pip install --ignore-installed -e git+https://github.com/okfn/ckan.git@ckan-1.5.1c#egg=ckan - sudo apt-get install python-pybabel python-psycopg2 python-lxml - sudo apt-get install python-sphinx python-pylons python-repoze.who - sudo apt-get install python-repoze.who-plugins python-tempita python-zope.interface - - Alternatively, if you are not using Ubuntu Lucid 10.04 you'll need to install them like this: +5. Install Additional Dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :: +CKAN has a set of dependencies it requires which you should install too. These are listed in three text files: requires/lucid_*.txt, followed by WebOb explicitly. - pip install --ignore-installed -r pyenv/src/ckan/requires/lucid_present.txt - - This will take a **long** time. Particularly the install of the ``lxml`` - package. +First we install two of the three lists of dependencies: - At this point you will need to deactivate and then re-activate your - virtual environment to ensure that all the scripts point to the correct - locations: +:: - :: - - deactivate - . pyenv/bin/activate + pip install --ignore-installed -r pyenv/src/ckan/requires/lucid_missing.txt -r pyenv/src/ckan/requires/lucid_conflict.txt + pip install webob==1.0.8 + +The ``--ignore-installed`` option ensures ``pip`` installs software into +this virtual environment even if it is already present on the system. -6. Setup a PostgreSQL database. +WebOb has to be installed explicitly afterwards because by installing pylons with `--ignore-installed` you end up with a newer (incompatible) version than the one that Pylons and CKAN need. + +Now to install the remaining dependencies in requires/lucid_present.txt and you are using Ubuntu Lucid 10.04 you can install the system versions:: + + sudo apt-get install python-pybabel python-psycopg2 python-lxml + sudo apt-get install python-sphinx python-pylons python-repoze.who + sudo apt-get install python-repoze.who-plugins python-tempita python-zope.interface + +Alternatively, if you are not using Ubuntu Lucid 10.04 you'll need to install them like this: + +:: + + pip install --ignore-installed -r pyenv/src/ckan/requires/lucid_present.txt + +This will take a **long** time. Particularly the install of the ``lxml`` +package. + +At this point you will need to deactivate and then re-activate your +virtual environment to ensure that all the scripts point to the correct +locations: + +:: + + deactivate + . pyenv/bin/activate + +6. Setup a PostgreSQL database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ List existing databases: :: - sudo -u postgres psql -l +sudo -u postgres psql -l It is advisable to ensure that the encoding of databases is 'UTF8', or internationalisation may be a problem. Since changing the encoding of PostgreSQL @@ -163,21 +165,22 @@ Install the Source .. tip :: - If you choose a database name, user or password which are different from the example values suggested below then you'll need to change the sqlalchemy.url value accordingly in the CKAN configuration file you'll create in the next step. +If you choose a database name, user or password which are different from the example values suggested below then you'll need to change the sqlalchemy.url value accordingly in the CKAN configuration file you'll create in the next step. Here we create a user called ``ckanuser`` and will enter ``pass`` for the password when prompted: :: - sudo -u postgres createuser -S -D -R -P ckanuser +sudo -u postgres createuser -S -D -R -P ckanuser Now create the database (owned by ``ckanuser``), which we'll call ``ckantest``: :: - sudo -u postgres createdb -O ckanuser ckantest +sudo -u postgres createdb -O ckanuser ckantest -7. Create a CKAN config file. +7. Create a CKAN config file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Make sure you are in an activated environment (see step 3) so that Python Paste and other modules are put on the python path (your command prompt will @@ -187,8 +190,8 @@ Install the Source :: - cd pyenv/src/ckan - paster make-config ckan development.ini +cd pyenv/src/ckan +paster make-config ckan development.ini If you used a different database name or password when creating the database in step 5 you'll need to now edit ``development.ini`` and change the @@ -196,25 +199,26 @@ Install the Source :: - sqlalchemy.url = postgresql://ckanuser:pass@localhost/ckantest +sqlalchemy.url = postgresql://ckanuser:pass@localhost/ckantest If you're using a remote host with password authentication rather than SSL authentication, use:: - sqlalchemy.url = postgresql://:@/ckan?sslmode=disable +sqlalchemy.url = postgresql://:@/ckan?sslmode=disable .. caution :: - Advanced users: If you have installed CKAN using the Fabric file capability (deprecated), - your config file will be called something like ``pyenv/ckan.net.ini``. - This is fine but CKAN probably won't be - able to find your ``who.ini`` file. To fix this edit ``pyenv/ckan.net.ini``, - search for the line ``who.config_file = %(here)s/who.ini`` and change it - to ``who.config_file = who.ini``. + Advanced users: If you have installed CKAN using the Fabric file capability (deprecated), + your config file will be called something like ``pyenv/ckan.net.ini``. + This is fine but CKAN probably won't be + able to find your ``who.ini`` file. To fix this edit ``pyenv/ckan.net.ini``, + search for the line ``who.config_file = %(here)s/who.ini`` and change it + to ``who.config_file = who.ini``. - We are moving to a new deployment system where this incompatibility - will be fixed. + We are moving to a new deployment system where this incompatibility + will be fixed. -8. Create database tables. +8. Create database tables +~~~~~~~~~~~~~~~~~~~~~~~~~ Now that you have a configuration file that has the correct settings for your database, you'll need to create the tables. Make sure you are still in an @@ -223,20 +227,21 @@ Install the Source If your config file is called development.ini: - :: +:: - paster --plugin=ckan db init + paster --plugin=ckan db init or if your config file is something else, you need to specify it. e.g.:: - paster --plugin=ckan db init --config=test.ckan.net.ini + paster --plugin=ckan db init --config=test.ckan.net.ini You should see ``Initialising DB: SUCCESS``. If the command prompts for a password it is likely you haven't set up the database configuration correctly in step 6. -9. Create the cache directory. +9. Create the cache directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You need to create the Pylon's cache directory specified by 'cache_dir' in the config file. @@ -245,23 +250,25 @@ Install the Source :: - mkdir data +mkdir data -10. Setup Solr. +10. Setup Solr +~~~~~~~~~~~~~~ - Set up Solr following the instructions on :ref:`solr-single` or :ref:`solr-multi-core` depending on your needs. +Set up Solr following the instructions on :ref:`solr-single` or :ref:`solr-multi-core` depending on your needs. - Set appropriate values for the ``ckan.site_id`` and ``solr_url`` config variables in your CKAN config file: +Set appropriate values for the ``ckan.site_id`` and ``solr_url`` config variables in your CKAN config file: - :: +:: - ckan.site_id=my_ckan_instance - solr_url=http://127.0.0.1:8983/solr + ckan.site_id=my_ckan_instance + solr_url=http://127.0.0.1:8983/solr -11. Run the CKAN webserver. +11. Run the CKAN webserver +~~~~~~~~~~~~~~~~~~~~~~~~~~ NB If you've started a new shell, you'll have to activate the environment again first - see step 3. @@ -270,12 +277,17 @@ Install the Source :: - paster serve development.ini +paster serve development.ini 12. Point your web browser at: http://127.0.0.1:5000/ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The CKAN homepage should load. + The CKAN homepage should load. Finally, make sure that tests pass, as described in :ref:`basic-tests`. +13. You are Done +~~~~~~~~~~~~~~~~ + You can now proceed to :doc:`post-installation`. +