Merge pull request #311 from fao89/6836

Document how to install from galaxy

CHANGES/6836.doc

@@ -0,0 +1 @@
+Document how to install from galaxy

docs/index.md

@@ -31,7 +31,7 @@ Ansibles Python interpreter must have the package installed:
 Variables
 ---------
 
-**Each role documents all the variables that it uses in its own README**. Some variables are
+**Each role documents all the variables that it uses**. Some variables are
 used by multiple roles. In that case, they are be documented in their primary role and mentioned in
 the `shared_variables` section the other roles.
 
@@ -59,37 +59,16 @@ It may be helpful to ensure that Ansible can communicate with the managed node.
 ansible all -m ping -u <managed_node_username>
 ```
 
-Using the example playbook
---------------------------
-
-The playbook has external requirements which should be installed from ansible-galaxy.
-
-```
-ansible-galaxy install -r requirements.yml
-```
-
-You should now be able to run the example playbook.
-
-Some of the roles used in the playbook use root privalages on the managed node, so when prompted,
-you will need to provide the password for the managed node user.
-
-```
-ansible-playbook playbooks/example-use/playbook.yml -u <managed_node_username> --ask-become-pass
-```
-
-To configure a custom install, you will need to set configuration variables. In the simplest case,
-they can be set in the playbook. See the ansible docs for more flexible idiomatic alternatives.
-
 Roles
 -----
 
 pulp_installer is equipped with the following roles:
 
-- [pulp](/roles/pulp/README.md): installs Pulp 3 from PyPi or source and provides basic config.
-- [pulp_content](/roles/pulp_content/README.md): install, configure, and set the state of pulp content app.
-- [pulp_database](/roles/pulp_database/README.md): optionally install a database, then configure for Pulp.
-- [pulp_redis](/roles/pulp_redis/README.md): install and start Redis, and install RQ in the Pulp virtualenv.
-- [pulp_resource_manager](/roles/pulp_resource_manager/README.md): install, configure, and set the state of the pulp resouce manager.
-- [pulp_webserver](/roles/pulp_webserver/README.md): install, configure, start, and enable a web server.
-- [pulp_workers](/roles/pulp_workers/README.md): install, configure, and set the state of pulp workers.
-- [pulp_devel](/roles/pulp_devel/README.md): installs useful tools and adds some config files for a Pulp 3 development environment.
+- [pulp](roles/pulp/): installs Pulp 3 from PyPi or source and provides basic config.
+- [pulp_content](roles/pulp_content): install, configure, and set the state of pulp content app.
+- [pulp_database](roles/pulp_database): optionally install a database, then configure for Pulp.
+- [pulp_redis](roles/pulp_redis): install and start Redis, and install RQ in the Pulp virtualenv.
+- [pulp_resource_manager](roles/pulp_resource_manager): install, configure, and set the state of the pulp resouce manager.
+- [pulp_webserver](roles/pulp_webserver): install, configure, start, and enable a web server.
+- [pulp_workers](roles/pulp_workers): install, configure, and set the state of pulp workers.
+- [pulp_devel](roles/pulp_devel): installs useful tools and adds some config files for a Pulp 3 development environment.

docs/quickstart.md

@@ -0,0 +1,109 @@
+Getting started
+===============
+
+Pulp 3 Ansible installer is a collection of roles to install or upgrade Pulp 3 hosted on galaxy:
+[https://galaxy.ansible.com/pulp/pulp_installer](https://galaxy.ansible.com/pulp/pulp_installer)
+
+Some plugins may require a prereq role, if so, you can find the prereq roles under pulp user here:
+[https://galaxy.ansible.com/pulp](https://galaxy.ansible.com/pulp)
+
+
+Requirements
+------------
+The collection requires [geerlingguy.postgresql](https://galaxy.ansible.com/geerlingguy/postgresql) role,
+which should be installed from ansible-galaxy.
+
+```
+ansible-galaxy install geerlingguy.postgresql
+```
+
+**NOTE:** Some plugins may require a prereq role, which is the case of `pulp_rpm`:
+```
+ansible-galaxy install pulp.pulp_rpm_prerequisites
+```
+
+Installation
+------------
+The recommended installation is from ansible-galaxy:
+
+```
+ansible-galaxy collection install pulp.pulp_installer
+```
+
+Using the example playbook
+--------------------------
+
+Some of the roles used in the playbook use root privileges on the managed node, so when prompted,
+you will need to provide the password for the managed node user.
+
+```
+ansible-playbook playbooks/example-use/playbook.yml -u <managed_node_username> --ask-become-pass
+```
+
+<script id="asciicast-335159" src="https://asciinema.org/a/335159.js" async data-autoplay="true" data-speed="2"></script>
+
+To configure a custom install, you will need to set configuration variables. In the simplest case,
+they can be set in the playbook. See the ansible docs for more flexible idiomatic alternatives.
+
+
+My first playbook
+-----------------
+As an example, we are going to write a playbook for installing `pulp_container` and `pulp_rpm`.
+You can learn more about the variables on the [roles section](https://pulp-installer.readthedocs.io/en/latest/roles/pulp/#role-variables)
+
+1 -  Installing pulp_installer collection:
+```
+ansible-galaxy collection install pulp.pulp_installer
+```
+
+2 -  Installing geerlingguy.postgresql role:
+```
+ansible-galaxy install geerlingguy.postgresql
+```
+
+3 - Writing the playbook (Example of playbook below):
+```
+vim install.yml
+```
+
+
+```yaml
+---
+- hosts: all
+  vars:
+    pulp_settings:
+      secret_key: << YOUR SECRET HERE >>
+      content_origin: "http://{{ ansible_fqdn }}"
+    pulp_default_admin_password: << YOUR PASSWORD HERE >>
+    pulp_install_plugins:
+      # galaxy-ng: {}
+      # pulp-ansible: {}
+      # pulp-certguard: {}
+      pulp-container: {}
+      # pulp-cookbook: {}
+      # pulp-deb: {}
+      # pulp-file: {}
+      # pulp-gem: {}
+      # pulp-maven: {}
+      # pulp-npm: {}
+      # pulp-python: {}
+      pulp-rpm:
+        prereq_role: "pulp.pulp_rpm_prerequisites" # RPM plugin needs a prereq_role: https://galaxy.ansible.com/pulp/pulp_rpm_prerequisites
+    roles:
+      - pulp.pulp_installer.pulp_database
+      - pulp.pulp_installer.pulp_workers
+      - pulp.pulp_installer.pulp_resource_manager
+      - pulp.pulp_installer.pulp_webserver
+      - pulp.pulp_installer.pulp_content
+    environment:
+    DJANGO_SETTINGS_MODULE: pulpcore.app.settings
+```
+4 - Installing `pulp_rpm` prereq role:
+```
+ansible-galaxy install pulp.pulp_rpm_prerequisites
+```
+5 - Running the playbook:
+```
+ansible-playbook install.yml -u <managed_node_username> --ask-become-pass
+```
+<script id="asciicast-335829" src="https://asciinema.org/a/335829.js" async data-autoplay="true" data-speed="2"></script>

mkdocs.yml

@@ -7,6 +7,7 @@ repo_url: https://github.com/pulp/pulp_installer
 theme: readthedocs
 nav:
   - Home: index.md
+  - Getting started: quickstart.md
   - contributing.md
   - Roles:
       - Pulp: roles/pulp.md
@@ -19,4 +20,3 @@ nav:
       - Pulp Workers: roles/pulp_workers.md
 markdown_extensions:
     - pymdownx.superfences
-

playbooks/example-source/group_vars/all

@@ -2,18 +2,20 @@
 pulp_default_admin_password: password
 pulp_source_dir: '/var/lib/pulp/devel/pulpcore'
 pulp_install_plugins:
-  # pulp-ansible:
-  #   source_dir: "/var/lib/pulp/devel/pulp_ansible"
   # galaxy-ng:
   #   source_dir: "/var/lib/pulp/devel/galaxy_ng"
+  # pulp-ansible:
+  #   source_dir: "/var/lib/pulp/devel/pulp_ansible"
   # pulp-certguard:
   #   source_dir: "/var/lib/pulp/devel/pulp-certguard"
+  # pulp-container:
+  #   source_dir: "/var/lib/pulp/devel/pulp_container"
   # pulp-cookbook:
   #   source_dir: "/var/lib/pulp/devel/pulp_cookbook"
   # pulp-deb:
   #   source_dir: "/var/lib/pulp/devel/pulp_deb"
-  # pulp-container:
-  #   source_dir: "/var/lib/pulp/devel/pulp_container"
+  pulp-file:
+    source_dir: "/var/lib/pulp/devel/pulp_file"
   # pulp-gem:
   #   source_dir: "/var/lib/pulp/devel/pulp_gem"
   # pulp-maven:
@@ -25,8 +27,6 @@ pulp_install_plugins:
   # pulp-rpm:
   #   source_dir: "/var/lib/pulp/devel/pulp_rpm"
   #   prereq_role: "pulp.pulp_rpm_prerequisites" # RPM needs a prereq_role: https://github.com/pulp/pulp_rpm_prerequisites
-  pulp-file:
-    source_dir: "/var/lib/pulp/devel/pulp_file"
 developer_user_home: /var/lib/pulp
 developer_user: pulp
 pulp_settings:

playbooks/example-use/group_vars/all

@@ -1,19 +1,19 @@
 ---
 pulp_default_admin_password: password
 pulp_install_plugins:
-  # pulp-ansible: {}
   # galaxy-ng: {}
+  # pulp-ansible: {}
   # pulp-certguard: {}
+  # pulp-container: {}
   # pulp-cookbook: {}
   # pulp-deb: {}
-  # pulp-container: {}
+  pulp-file: {}
   # pulp-gem: {}
   # pulp-maven: {}
   # pulp-npm: {}
   # pulp-python: {}
   # pulp-rpm:
   #   prereq_role: "pulp.pulp_rpm_prerequisites" # RPM needs a prereq_role: https://galaxy.ansible.com/pulp/pulp_rpm_prerequisites
-  pulp-file: {}
 pulp_settings:
   secret_key: secret
   content_origin: "http://{{ ansible_fqdn }}"

roles/pulp/README.md

@@ -5,8 +5,8 @@ Ansible role that installs Pulp 3 from PyPi or source and provides basic config.
 
 The default administrative user for the Pulp application is: 'admin'
 
-Role Variables:
----------------
+Role Variables
+--------------
 * `pulp_install_plugins`: A nested dictionary of plugin configuration options.
   Defaults to "{}", which will not install any plugins.
     * *Dictionary Key*: The pip installable plugin name. This is defined in each plugin's `setup.py`. **Required**.
@@ -96,8 +96,8 @@ Role Variables:
   Only affects RHEL7 (RHEL8 no longer has an optional repo.)
 
 
-Shared Variables:
------------------
+Shared Variables
+----------------
 
 * `ansible_python_interpreter`: **Required**. Path to the Python interpreter.
 
@@ -109,14 +109,14 @@ This role is required by the `pulp_database` role and uses some variables from i
 
 * `pulp_settings_db_defaults`: See pulp_database README.
 
-Operating System Variables:
----------------------------
+Operating System Variables
+--------------------------
 
 Each currently supported operating system has a matching file in the "vars"
 directory.
 
-Idempotency:
-------------
+Idempotency
+-----------
 This role is idempotent by default. It is dependent on these settings remaining `false`:
 * Every `upgrade` under `pulp_install_plugins`
 

roles/pulp_content/README.md

@@ -3,8 +3,8 @@ pulp_content
 
 Install, configure, and set the state of pulp content app.
 
-Variables:
-----------
+Variables
+---------
 
 * `pulp_content_bind`: Interface and Port where Pulp Content `gunicorn` service will listen.
 
@@ -13,8 +13,8 @@ to the `--bind` parameter of the gunicorn service.
 
 Defaults to `127.0.0.1:24816`
 
-Shared variables:
------------------
+Shared variables
+----------------
 
 * `ansible_python_interpreter`: **Required**. Path to the Python interpreter.
 

roles/pulp_database/README.md

@@ -9,8 +9,8 @@ More specifically, this role does the following:
 2. Install the Python bindings to interact with the specified database.
 3. Create and run migrations.
 
-Role Variables:
----------------
+Role Variables
+--------------
 
 * `pulp_settings_db_defaults`: This variable **should not be changed by users**, but serves as the
     defaults. Users wishing to set their own values should use the user-facing variable
@@ -21,8 +21,8 @@ Role Variables:
     [Django docs](https://docs.djangoproject.com/en/2.1/ref/settings/#databases) for more
     information.
 
-Shared Variables:
------------------
+Shared Variables
+----------------
 
 * `ansible_python_interpreter`: **Required**. Path to the Python interpreter.
   This role sets the default to "auto", which is now more robust than
@@ -37,8 +37,8 @@ variables which are documented in that role:
 * `pulp_default_admin_password`
 * `pulp_settings`
 
-Operating Systems Variables:
-----------------------------
+Operating Systems Variables
+---------------------------
 
 Each currently supported operating system has a matching file in the "vars"
 directory.

roles/pulp_devel/README.md

@@ -26,8 +26,8 @@ developer_user_home: /home/vagrant
 pulp_default_admin_password: password
 ```
 
-Shared variables:
------------------
+Shared variables
+----------------
 
 * `ansible_python_interpreter`: **Required**. Path to the Python interpreter.
 
@@ -44,8 +44,8 @@ used in that role.
 * `pulp_workers`
 
 
-Aliases:
------------------
+Aliases
+-------
 
 This role provides the following aliases:
 

roles/pulp_redis/README.md

@@ -3,8 +3,8 @@ pulp_redis
 
 Install and start Redis, and install RQ in the Pulp virtualenv.
 
-Shared Variables:
------------------
+Shared Variables
+----------------
 
 * `ansible_python_interpreter`: **Required**. Path to the Python interpreter.
 
@@ -17,8 +17,8 @@ role. When not used together, this role provides identical defaults.
   dependencies. Defaults to "/usr/local/lib/pulp".
 
 
-Operating Systems Variables:
-----------------------------
+Operating Systems Variables
+---------------------------
 
 Each currently supported operating system has a matching file in the "vars"
 directory.