diff --git a/doc/source/index.rst b/doc/source/index.rst index d4d30987..b98ca97e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,10 +12,10 @@ Content: .. toctree:: :maxdepth: 2 + refstack_setup_via_ansible overview contributing refstack - run_in_docker/index vendor_product_management/index uploading_private_results test_result_management diff --git a/doc/source/refstack.rst b/doc/source/refstack.rst index dbe382eb..325e0247 100644 --- a/doc/source/refstack.rst +++ b/doc/source/refstack.rst @@ -170,15 +170,15 @@ name instead of the IP. **Option 1 - Use Official Endpoint** -Using the official site is probably the easiest option as no additional -configuration is needed besides the hosts file modifications as noted -above. RefStack, by default, points to this endpoint. +Using the official site is probably the easiest as no additional configuration +is needed besides the hosts file modifications as noted above. RefStack, by +default, points to this endpoint. **Option 2 - Use Local Endpoint** Instructions for setting this up are outside of the scope of this doc, but you can get started at -`Openstackid project `__ . +`Openstackid project `__ . You would then need to modify the ``openstack_openid_endpoint`` field in the ``[osid]`` section in refstack.conf to match the local endpoint. diff --git a/doc/source/run_in_docker/Option1AnsiblePlaybook.rst b/doc/source/refstack_setup_via_ansible.rst similarity index 88% rename from doc/source/run_in_docker/Option1AnsiblePlaybook.rst rename to doc/source/refstack_setup_via_ansible.rst index 7752e2a8..daba2340 100644 --- a/doc/source/run_in_docker/Option1AnsiblePlaybook.rst +++ b/doc/source/refstack_setup_via_ansible.rst @@ -1,16 +1,16 @@ -==================================== -Option 1 - Using an ansible playbook -==================================== +============================================================= +Use Ansible playbook to set up a local refstack instance +============================================================= These steps are meant for RefStack developers to help them with setting up a local refstack instance. -In production RefStack server is managed by a set of playbooks and ansible roles +In production RefStack server is managed by a set of playbooks and Ansible roles defined in `system-config `__ -repository. This option takes advantage of those. +repository. Below instructions use these Ansible capabilities. -The RefStack server is running on Ubuntu 20.04 LTS in the production. +The RefStack server runs on Ubuntu 20.04 LTS in the production. -You can find an ansible playbook in ``playbooks`` directory which semi-automates +You can find an Ansible playbook in ``playbooks`` directory which semi-automates the process of running refstack server in a container. Execute the playbook by:: diff --git a/doc/source/run_in_docker/Option2UsingAScript.rst b/doc/source/run_in_docker/Option2UsingAScript.rst deleted file mode 100644 index 052ef08c..00000000 --- a/doc/source/run_in_docker/Option2UsingAScript.rst +++ /dev/null @@ -1,76 +0,0 @@ -========================= -Option 2 - Using a script -========================= - -NOTE: This is currently outdated, follow the Option 1 for now. - -The main purpose of the ``run-in-docker`` script is to provide a -convenient way to create a local setup of RefStack inside a Docker -container. It should be helpful for new developers and also for testing -new features. - -Requirements: -------------- - -- ``Docker >= 1.6`` (How to update on - `Ubuntu `__) - -How to use: ------------ - -Just run the ``run-in-docker`` script, but is important to first set -env[REFSTACK\_HOST] with the public host/IP for your local API. If you -want to test RefStack with OpenStackid you should point a valid local -alias here. For example: - -``export REFSTACK_HOST=myrefstack.com`` - -By default 127.0.0.1 is used. - -After it completes, check that the site is running on https://127.0.0.1. - -The script will build a RefStack docker image with all dependencies, and -will run a container from this image. By default, RefStack will run -inside this container. You also can run ``run-in-docker bash`` to get -access into the container. If you stop the RefStack server by pressing -'Ctrl-C', the container is kept alive and will be re-used next time. - -You can customize the RefStack API config by editing -``docker/templates/refstack.conf.tmpl``. It is a bash template, so you -can use ${SOME\_ENV\_VARIABLE} in it. - -This script can make the reviewing process much easier because it -creates separate containers for each review. Containers get names in the -form refstack\_{REVIEW-TOPIC}. Database schema changes are automatically -handled, too, where the script creates a data container for each -database revision (refstack\_data\_{DATA-BASE-REVISON}) and reuses it -where possible. For example, if a new review uses an existing database -revision, that database container will be used. - -Available script options: -------------------------- - -- ``-r`` Force delete the RefStack container and run it again. This - will update the RefStack config from template noted above. -- ``-i`` Run a container with isolated MySQL data. By default MySQL - data is stored in a refstack\_data\_{DATA-BASE-REVISON} container. It - reuses this container if such one exists. If you want to drop the DB - data, just execute - ``sudo docker rm refstack_data_{DATA-BASE-REVISON}``. -- ``-b`` Force delete RefStack image and build it again. This rebuilds - the Python and JS environment for RefStack. -- ``-d`` Turn on debug information. -- ``-h`` Print usage message. - -Useful in-container commands/aliases: -------------------------------------- - -- ``api-up`` - sync project and run the RefStack API -- ``api-init-db`` - initialize the RefStack database -- ``api-db-version`` - get current migration version of the RefStack - database -- ``api-sync`` - sync project files in the container with the project - files on the host -- ``activate`` - activate the python virtual env -- ``mysql`` - open the MySQL console - diff --git a/doc/source/run_in_docker/index.rst b/doc/source/run_in_docker/index.rst deleted file mode 100644 index 9a174f79..00000000 --- a/doc/source/run_in_docker/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Run-in-docker manual -==================== - -.. toctree:: - :maxdepth: 1 - :includehidden: - - Option1AnsiblePlaybook - Option2UsingAScript