diff --git a/doc/source/devref/development_environment.rst b/doc/source/devref/development_environment.rst index ef89ee1eb8..883c845307 100644 --- a/doc/source/devref/development_environment.rst +++ b/doc/source/devref/development_environment.rst @@ -33,25 +33,51 @@ Prerequisites This document assumes you are using an Ubuntu, Fedora, or openSUSE platform and that you have the following tools pre-installed on your system: -- Python_ 2.7 and 3.5, as the programming language; +- python_ 2.7 and 3.5, as the programming language; - git_, as the version control tool; **Reminder**: If you are successfully using a different platform, or a different version of the above, please document your configuration here! .. _git: http://git-scm.com/ -.. _Python: http://www.python.org/ -Getting the latest code -======================= +Installing from source +====================== -Make a clone of the code from our git repository and enter the directory: +The source install instructions specifically avoid using platform specific +packages. Instead, we recommend using the source for the code and the Python +Package Index (PyPi_) for development environment installations.. + +.. _PyPi: http://pypi.python.org/pypi + +It's expected that your system already has python_, pip_, and git_ available. + +.. _python: http://www.python.org +.. _pip: http://www.pip-installer.org/en/latest/installing.html +.. _git: http://git-scm.com/ + +Clone the keystone repository: .. code-block:: bash $ git clone https://git.openstack.org/openstack/keystone.git $ cd keystone +Install the keystone web service: + +.. code-block:: bash + + $ pip install -e . + +.. NOTE:: + + This step is guaranteed to fail if you do not have the proper binary + dependencies already installed on your development system. Maintaining a + list of platform-specific dependencies is outside the scope of this + documentation, but is within scope of DEVSTACK_. + +.. _DEVSTACK: https://docs.openstack.org/developer/devstack/ + Development environment ======================= @@ -59,13 +85,34 @@ For setting up the Python development environment and running `tox` testing environments, please refer to the `Project Team Guide: Python Project Guide`_, the OpenStack guide on wide standard practices around the use of Python. -That documentation will guide you to configure your development environment -and run keystone tests using `tox`, which uses virtualenv_ to isolate the Python +That documentation will help you configure your development environment and run +keystone tests using `tox`, which uses virtualenv_ to isolate the Python environment. After running it, notice the existence of a `.tox` directory. .. _`Project Team Guide: Python Project Guide`: https://docs.openstack.org/project-team-guide/project-setup/python.html .. _virtualenv: http://www.virtualenv.org/ +Deploying configuration files +============================= + +You should be able to run keystone after installing via pip. Additional +configuration files are required, however. The following files are required in +order to run keystone: + +* ``keystone.conf`` +* ``keystone-paste.ini`` + +You can generate a sample configuration file using ``tox -e genconfig``. You +can also generate sample policy files using ``tox -e genpolicy``. Please refer +to :doc:`../configuration` for guidance on specific configuration options or to +view a sample paste file. + +Bootstrapping a test deployment +=============================== + +You can use the ``keystone-manage bootstrap`` command to pre-populate the +database with necessary data. + Verifying keystone is set up ============================ @@ -78,6 +125,13 @@ Once set up, you should be able to invoke Python and import the libraries: If you can import keystone without a traceback, you should be ready to move on to the next sections. +You can run keystone using a host of wsgi implementations or web servers. The +following uses ``uwsgi``: + +.. code-block:: bash + + $ uwsgi --http 127.0.0.1:35357 --wsgi-file $(which keystone-wsgi-admin) + Database setup ============== diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst index 227b22fa65..55e0a87b69 100644 --- a/doc/source/getting-started/index.rst +++ b/doc/source/getting-started/index.rst @@ -5,7 +5,6 @@ Getting Started .. toctree:: :maxdepth: 1 - installing.rst performance.rst architecture.rst policy_mapping.rst diff --git a/doc/source/getting-started/installing.rst b/doc/source/getting-started/installing.rst deleted file mode 100644 index 51c8097ff3..0000000000 --- a/doc/source/getting-started/installing.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. - Copyright 2012 OpenStack Foundation - Copyright 2012 Nebula, Inc - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=================== -Installing Keystone -=================== - -This document describes how to install Keystone in order to use it. If you are -intending to develop on or with Keystone, please read -:doc:`../devref/index` and :doc:`../devref/development_environment`. - -Installing from Source ----------------------- - -The source install instructions specifically avoid using platform specific -packages, instead using the source for the code and the Python Package Index -(PyPi_). - -.. _PyPi: http://pypi.python.org/pypi - -It's expected that your system already has python_, pip_, and git_ available. - -.. _python: http://www.python.org -.. _pip: http://www.pip-installer.org/en/latest/installing.html -.. _git: http://git-scm.com/ - -Clone the Keystone repository: - -.. code-block:: bash - - $ git clone https://git.openstack.org/openstack/keystone.git - $ cd keystone - -Install the Keystone web service: - -.. code-block:: bash - - $ pip install . - -.. NOTE:: - - This step is guaranteed to fail if you do not have the proper binary - dependencies already installed on your development system. Maintaining a - list of platform-specific dependencies is outside the scope of this - documentation, but is within scope of DEVSTACK_. - -You should have all the pieces you need to run Keystone installed on your -system. The following commands should be available on the command-line path: - -* ``keystone`` the Keystone client, used to interact with Keystone -* ``keystone-manage`` used to bootstrap Keystone data - -You will find sample configuration files in ``etc/``: - -* ``keystone.conf`` -* ``keystone-paste.ini`` -* ``logging.conf`` -* ``policy.json`` -* ``default_catalog.templates`` - -From here, refer to :doc:`../configuration` to choose which backend drivers to -enable and use. Once configured, you should be able to run Keystone by issuing -the command: - -.. code-block:: bash - - $ uwsgi --http 127.0.0.1:35357 --wsgi-file $(which keystone-wsgi-admin) - -By default, this will show logging on the console from which it was started. -Once started, you can initialize data in Keystone for use with the rest of -OpenStack, as described in :doc:`../configuration`. - -An excellent reference implementation of setting up Keystone is DEVSTACK_, -most commonly used for development and testing setup of not only Keystone, -but all of the core OpenStack projects. - -.. _DEVSTACK: https://docs.openstack.org/developer/devstack/ - -The script with the latest examples of initializing data in Keystone is a -bash script called `lib/keystone`_ - -.. _lib/keystone: https://git.openstack.org/cgit/openstack-dev/devstack/tree/lib/keystone - -Installing from packages: Ubuntu --------------------------------- - -To install keystone on Ubuntu: - -.. code-block:: bash - - $ sudo apt-get install keystone - -In using Ubuntu's packages, the packages will set up a user account for -the Keystone service (`keystone`), and place default configurations in -``/etc/keystone``. As of this writing, the defaults for Keystone backends are -all SQL based, stored locally in SQLite. - -Once installed, you still need to initialize data in Keystone, which you can -find described in :doc:`../configuration`. - -Installing from packages: Fedora --------------------------------- - -To install Keystone on Fedora refer to the steps found in the `OpenStack -Install Guide`_. - -To install the packages: - -.. code-block:: bash - - $ sudo yum install openstack-keystone - -Once installed, you still need to initialize data in Keystone, which you can -find described in :doc:`../configuration`. - -.. _`OpenStack Install Guide`: https://docs.openstack.org/liberty/install-guide-rdo/keystone-install.html