Re-import docs from Upstream 24.6.1 repo (#157)

* Re-import docs.
Will need to start going through the files one by one to ensure accuracy.

* Update requirements.txt for docs

* Rename some files

* Delete backup files

* Rename image

Author: cigamit

.gitignore

@@ -172,6 +172,7 @@ awx/ui_next/build
 
 # Docs build stuff
 docs/docsite/build/
+docs/docsite/venv/
 _readthedocs/
 
 # Pyenv

docs/ansible_runner_integration.md

@@ -0,0 +1,19 @@
+## Ansible Runner Integration Overview
+
+Much of the code in Ascender around ansible and `ansible-playbook` invocation has been removed and put into the project `ansible-runner`. Ascender now calls out to `ansible-runner` to invoke ansible and `ansible-playbook`.
+
+### Lifecycle
+
+In Ascender, a task of a certain job type is kicked off (_i.e._, RunJob, RunProjectUpdate, RunInventoryUpdate, etc.) in `awx/main/tasks/jobs.py`. A temp directory is built to house `ansible-runner` parameters (_i.e._, `envvars`, `cmdline`, `extravars`, etc.). The `temp` directory is filled with the various concepts in Ascender (_i.e._, `ssh` keys, `extra vars`, etc.). The code then builds a set of parameters to be passed to the `ansible-runner` Python module interface, `ansible-runner.interface.run()`. This is where Ascender passes control to `ansible-runner`. Feedback is gathered by Ascender via callbacks and handlers passed in.
+
+The callbacks and handlers are:
+* `event_handler`: Called each time a new event is created in `ansible-runner`. Ascender will dispatch the event to `redis` to be processed on the other end by the callback receiver.
+* `cancel_callback`: Called periodically by `ansible-runner`; this is so that Ascender can inform `ansible-runner` if the job should be canceled or not. Only applies for system jobs now, and other jobs are canceled via receptor.
+* `finished_callback`: Called once by `ansible-runner` to denote that the process that was asked to run is finished. Ascender will construct the special control event, `EOF`, with the associated total number of events that it observed.
+* `status_handler`: Called by `ansible-runner` as the process transitions state internally. Ascender uses the `starting` status to know that `ansible-runner` has made all of its decisions around the process that it will launch. Ascender gathers and associates these decisions with the Job for historical observation.
+
+### Debugging
+
+If you want to debug `ansible-runner`, then set `Ascender_CLEANUP_PATHS=False`, run a job, observe the job's `Ascender_PRIVATE_DATA_DIR` property, and go the node where the job was executed and inspect that directory.
+
+If you want to debug the process that `ansible-runner` invoked (_i.e._, Ansible or `ansible-playbook`), then observe the Job's `job_env`, `job_cwd`, and `job_args` parameters.

docs/auth/README.md

@@ -0,0 +1,27 @@
+This folder describes third-party authentications supported by Ascender. These authentications can be configured and enabled inside Ascender.
+
+When a user wants to log into Ascender, she can explicitly choose some of the supported authentications to log in instead of Ascender's own authentication using username and password. Here is a list of such authentications:
+* Google OAuth2
+* Github OAuth2
+* Github Organization OAuth2
+* Github Team OAuth2
+* Github Enterprise OAuth2
+* Github Enterprise Organization OAuth2
+* Github Enterprise Team OAuth2
+* Microsoft Azure Active Directory (AD) OAuth2
+
+On the other hand, the other authentication methods use the same types of login info (username and password), but authenticate using external auth systems rather than Ascender's own database. If some of these methods are enabled, Ascender will try authenticating using the enabled methods *before Ascender's own authentication method*. The order of precedence is:
+* LDAP
+* RADIUS
+* TACACS+
+* SAML
+
+Ascender will try authenticating against each enabled authentication method *in the specified order*, meaning if the same username and password is valid in multiple enabled auth methods (*e.g.*, both LDAP and TACACS+), Ascender will only use the first positive match (in the above example, log a user in via LDAP and skip TACACS+).
+
+## Notes:
+SAML users, RADIUS users and TACACS+ users are categorized as 'Enterprise' users. The following rules apply to Enterprise users:
+
+  * Enterprise users can only be created via the first successful login attempt from remote authentication backend.
+  * Enterprise users cannot be created/authenticated if non-enterprise users with the same name has already been created in Ascender.
+  * Ascender passwords of Enterprise users should always be empty and cannot be set by any user if there are enterprise backends enabled.
+  * If enterprise backends are disabled, an Enterprise user can be converted to a normal Ascender user by setting password field. But this operation is irreversible (the converted Ascender user can no longer be treated as Enterprise user).

docs/auth/ldap.md

@@ -0,0 +1,68 @@
+# LDAP
+The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry-standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network.
+
+
+# Configure LDAP Authentication
+
+Please see the [Tower documentation](https://docs.ansible.com/ansible-tower/latest/html/administration/ldap_auth.html) as well as [Ansible blog post](https://www.ansible.com/blog/getting-started-ldap-authentication-in-ansible-tower) for basic LDAP configuration.
+
+LDAP Authentication provides duplicate sets of configuration fields for authentication with up to six different LDAP servers.
+The default set of configuration fields take the form `AUTH_LDAP_<field name>`. Configuration fields for additional LDAP servers are numbered `AUTH_LDAP_<n>_<field name>`.
+
+
+## Test Environment Setup
+
+Please see `README.md` of this repository: https://github.com/ansible/deploy_ldap
+
+
+# Basic Setup for FreeIPA
+
+LDAP Server URI (append if you have multiple LDAPs)    
+`ldaps://{{serverip1}}:636`
+
+LDAP BIND DN (How to create a bind account in [FreeIPA](https://www.freeipa.org/page/Creating_a_binddn_for_Foreman)   
+`uid=awx-bind,cn=sysaccounts,cn=etc,dc=example,dc=com`
+
+LDAP BIND PASSWORD   
+`{{yourbindaccountpassword}}`
+
+LDAP USER DN TEMPLATE   
+`uid=%(user)s,cn=users,cn=accounts,dc=example,dc=com`
+
+LDAP GROUP TYPE   
+`NestedMemberDNGroupType`
+
+LDAP GROUP SEARCH
+```
+[
+"cn=groups,cn=accounts,dc=example,dc=com",
+"SCOPE_SUBTREE",
+"(objectClass=groupOfNames)"
+]
+```
+
+LDAP USER ATTRIBUTE MAP
+```
+{
+"first_name": "givenName",
+"last_name": "sn",
+"email": "mail"
+}
+```
+
+LDAP USER FLAGS BY GROUP
+```
+{
+"is_superuser": "cn={{superusergroupname}},cn=groups,cn=accounts,dc=example,dc=com"
+}
+```
+
+LDAP ORGANIZATION MAP
+```
+{
+"{{yourorganizationname}}": {
+"admins": "cn={{admingroupname}},cn=groups,cn=accounts,dc=example,dc=com",
+"remove_admins": false
+}
+}
+```