Update self-hossted agent documentaiton (#942)

update documentation

azure-pipelines/self-agent-test.yml

@@ -0,0 +1,23 @@
+# Simple pipeline to test a self hosted agent.
+# Set trigger and pull request trigger to none, since we do not need continuous integration.
+
+trigger: none
+
+pr: none
+
+
+jobs:
+
+- job: 'Test_Self_Hosted_Agent'
+  pool:
+    name: Linux
+
+
+  steps:
+  - bash: |
+          ls
+    displayName: List remote server files
+
+  - bash: |
+          python /home/youssef/helloworld.py
+    displayName: Run local file

docs/workflow/azure_links.inc

@@ -1,15 +1,22 @@
 
 .. azure stuff
-.. _Azure Devops: http://azure.microsoft.com/en-us/services/devops/?nav=mi
-.. _Azure ssh-task: http://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/install-ssh-key?view=azure-devops#example-setup-using-github
-.. _Azure secure files: http://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines
-.. _Azure variables: http://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables
-.. _Azure secure files: http://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines
-.. _Azure task: http://github.com/microsoft/azure-pipelines-tasks
+.. _azure devops: http://azure.microsoft.com/en-us/services/devops/?nav=mi
+.. _azure ssh-task: http://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/install-ssh-key?view=azure-devops#example-setup-using-github
+.. _azure secure files: http://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines
+.. _azure variables: http://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables
+.. _azure secure files: http://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines
+.. _azure task: http://github.com/microsoft/azure-pipelines-tasks
+.. _azure pipelines agent releases: https://github.com/Microsoft/azure-pipelines-agent/releases
+.. _azure self hosted agents: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/agents?view=azure-devops#install
+.. _personal access token PAT: https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops
+.. _self agent services: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/v2-linux?view=azure-devops#run-as-a-systemd-service
+.. _agent pool security roles: https://docs.microsoft.com/en-us/azure/devops/organizations/security/about-security-roles?view=azure-devops#agent-pool-security-roles-project-level
+.. _service file: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/v2-linux?view=azure-devops#service-files
 
 .. general stuff
 .. _Continuous Integration: https://en.wikipedia.org/wiki/Continuous_integration
 
 .. |emdash| unicode:: U+02014
 
-.. vim: ft=rstS
+.. vim: ft=rstS
+

docs/workflow/continuous_integration.rst

@@ -210,8 +210,66 @@ Or if you prefer to use multiple virtual machines and specity the maximum that c
             vm_Image: 'macOS-10.13'
             miniconda.url: 'http://repo.continuum.io/miniconda/Miniconda2-latest-mac-x86_64.sh'
         maxParallel: 4
+        
+Installing and running a self hosted agent
+------------------------------------------
 
+Microsoft supplies multiple hosted agents for running virtual machines, but it is useful to create a self hosted
+agent for incremental builds and the dependancy on local environments.
 
+To add a new agent or agent pool, you must have administrator priveledges. See `agent pool security roles`_ to add a new administrator to an agent pool or for all the agent pools.
+
+You can view your current lists of agents for each agent pool from: https://dev.azure.com/{your_organization}/_settings/agentpools.
+
+First decide if you will add your agent to an already exiting agent pool, or if you wish to add a new pool, by clicking on Add pool.
+If you choose to add a new pool, make sure to click on securtiy and add permissions to your team/self (you cannot directly add your own account), as well as granting access permission to all pipelines, or a specific pipeline.
+The first pool "Default" is owned by azure pipelines, and you cannot add pools to it without having even further permissions.
+
+To give someone all security privileges:
+  - Go to http://dev.azure.com/{your_organization}/_settings/permissions
+  - Click on {your_organization}\Project Collection Administrators
+  - Click on Members
+  - Click Add members on the top right.
+
+Then, you must generate a `personal access token PAT`_, to add any downloaded self agents. 
+
+For the scope, make sure to select: Agent Pools (read, manage).
+
+To download the latest available agents, see `Azure pipelines agent releases`_.
+
+Create the agent (for Linux and Mac_OS)::
+
+    ~/$ mkdir myagent && cd myagent
+    ~/myagent$ tar zxvf ~/Downloads/download_agent.tar.gz
+
+and configure it::
+
+    ~/myagent$ ./config.sh
+
+Here, you will input your organization name (https://dev.azure.com/{your_organization}), your generated PAT, agent pool name, and agent name. 
+
+To run the session interactively::
+
+    ~/myagent$ ./run.sh
+
+To run, stop, or check the status non-interactively, create the service file::
+
+    ~/myagent$ sudo ./svc install
+
+Manage it through::
+
+    ~/myagent$ sudo ./svc start
+    ~/myagent$ sudo ./svc stop
+    ~/myagent$ sudo ./svc status
+
+To uninstall ::
+
+    ~/myagent$ sudo ./svc uninstall
+
+For adding environmental variables or editing the `service file`_, 
+see `self agent services`_ 
+
+For more details, see `Azure self hosted agents`_ 
 
 Additional references
 --------------------