From 0c55bae6550d6e7099d42f55e6f55a89ddd585e0 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Tue, 18 Jul 2017 16:22:56 +0000 Subject: [PATCH] Move development environment setup to contributor docs The development environment setup docs were duplicated in two separate places. This commit remove it from the "Getting Started" section and into the contributor guide. Change-Id: If243fd9896be286f9d4c80139eb3cb86600f0052 --- doc/source/devref/development_environment.rst | 68 ++++++++- doc/source/getting-started/index.rst | 1 - doc/source/getting-started/installing.rst | 130 ------------------ 3 files changed, 61 insertions(+), 138 deletions(-) delete mode 100644 doc/source/getting-started/installing.rst 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