deployment

Author: Tom-Willemsen

doc/Deployment.md

@@ -1,25 +1,59 @@
+# Releases
+
+```{toctree}
+:glob:
+:titlesonly:
+
+deployment/Creating-a-release
+deployment/Manual-system-tests
+```
+
 # Deployment
 
-- [Deployment Strategy](Deployment-strategy)
-- [Creating a Release](Creating-a-release)
-- [How to deploy IBEX and EPICS on an instrument control PC](Deployment-on-an-Instrument-Control-PC)
-- [Deploy script workflow](Deploy-script-workflow)
-- [How to deploy IBEX to training machine](IBEX-Deployment-on-Training-machine)
-- [How to release a single IOC to an instrument](Release-Single-IOC)
-- [How to migrate an instrument from SECI to IBEX](Migrate-an-Instrument-Control-PC)
-- [How to add the instrument to the list of available instruments](Making-an-Instrument-Available-from-the-GUI)
-- [Upgrade Java](Upgrade-java)
-- [Manual System Tests](Manual-system-tests)
-- [Manual System Tests Results](Manual-System-Tests-Results)
-- [Installing and upgrading MySQL](Installing-and-Upgrading-MySQL)
-- [Disaster Recovery Testing](Disaster-Recovery-Testing)
-- [Virtual System Creation](Virtual-System-Creation)
-- [Autostart IBEX on Computer Restart](Autostart-IBEX-on-Computer-Restart)
-- [Quick Deploy](Quick-Deploy) (e.g. for Demo and R78)
-- [Upgrade ISISICP](Upgrade-ISISICP)
-- [Modifying Plugins on a Deployed Client](Modifying-Plugins-on-a-Deployed-Client)
-- [Mount or create IBEX VHDs](Mount-or-create-IBEX-VHDs)
-- [NPort Install](NPort-install)
-- [Instrument definition (like mapped drives) "Instrument Machine standards.doc"](http://www.facilities.rl.ac.uk/isis/computing/instruments/Instrument%20Documents/Forms/AllItems.aspx)
-- [Updating Instrument Machines](Updating-Instrument-Machines)
-- [Reviewing Deployment Tickets](Reviewing-Deploy-Tickets)
+## IBEX
+
+```{toctree}
+:glob:
+:titlesonly:
+
+deployment/Updating-Instrument-Machines
+deployment/Deployment-on-an-Instrument-Control-PC
+deployment/IBEX-Deployment-on-Training-machine
+deployment/Autostart-IBEX-on-Computer-Restart
+deployment/Making-an-Instrument-Available-from-the-GUI
+deployment/Reviewing-Deploy-Tickets
+deployment/Deploy-script-workflow
+```
+
+## Supporting software
+
+```{toctree}
+:glob:
+:titlesonly:
+
+deployment/Installing-and-Upgrading-MySQL
+deployment/NPort-install
+deployment/Upgrade-Java
+deployment/Upgrade-ISISICP
+```
+
+# Patching
+
+```{toctree}
+:glob:
+:titlesonly:
+
+deployment/Modifying-Code-on-an-instrument
+deployment/Modifying-Device-on-an-Instrument
+deployment/Release-Single-IOC
+deployment/Modifying-Plugins-on-a-Deployed-Client
+```
+
+# VHD Build & Deployments
+
+```{toctree}
+:glob:
+:titlesonly:
+
+deployment/Mount-or-create-IBEX-VHDs
+```

doc/Processes.md

@@ -1,18 +1,4 @@
-# Processes
-
-Various Processes or tasks and info into how they should work. Remember rules can be bent or broken but think about why you are doing that.
-
-## Patching
-
-```{toctree}
-:glob:
-:titlesonly:
-
-processes/Modifying-Code-on-an-instrument
-processes/Modifying-Device-on-an-Instrument
-```
-
-## Development
+# Development Processes
 
 ```{toctree}
 :glob:
@@ -25,6 +11,8 @@ processes/Dependency-Updates
 processes/External-Contributions
 ```
 
+# Meetings
+
 ## Internal meetings
 
 ```{toctree}
@@ -49,7 +37,7 @@ processes/Regular-Demos-of-IBEX-to-Scientists
 processes/Training-Instrument-Scientists-in-IBEX
 ```
 
-## Project management
+# Project Management
 
 ```{toctree}
 :glob:
@@ -61,7 +49,7 @@ processes/Sprint-Burn-down-Chart
 processes/Prioritisation-of-Tickets
 ```
 
-## Admin
+# Admin
 
 ```{toctree}
 :glob:

doc/conf.py

@@ -64,6 +64,7 @@
 html_theme_options = {
     "logo_only": False,
     "style_nav_header_background": "#343131",
+    'body_max_width': None,
 }
 html_favicon = "favicon.svg"
 

doc/uncategorised/Autostart-IBEX-on-Computer-Restart.md renamed to doc/deployment/Autostart-IBEX-on-Computer-Restart.md

@@ -1,6 +1,6 @@
-> [Wiki](Home) > [Deployment](Deployment) > [Autostart IBEX on Computer Restart](Autostart-IBEX-on-Computer-Restart)
+# Auto-start IBEX on Computer Restart
 
-# Windows Server 2012 R2
+## Windows Server 2012 R2
 
 **This appears to work but doesn't because the user does not have interactive mode permissions. There is a ticket to sort this out**
 

doc/uncategorised/Creating-a-release.md renamed to doc/deployment/Creating-a-release.md

@@ -1,4 +1,4 @@
-> [Wiki](Home) > [Deployment](Deployment) > Creating a release
+# Creating a release
 
 ## Understanding Java Licensing
 Make sure you [understand how Java is licensed](Understanding-Java-Licensing), so that we do not inadvertently make ISIS liable for licensing fees.
@@ -147,6 +147,3 @@ The is a release when a change needs to be made between standard releases; i.e.
 1. cd to EPICS
 1. checkout release branch and pull
 1. update submodule reference, commit and push.
-
-### Note: Minor upgrades to v11.0.0.
-**WARNING:** If branching off the `v11.0.0` to make a release, you will need to re-add changes made in this [commit](https://github.com/ISISComputingGroup/EPICS-upgrade/commit/9b92ba915ca7cfdd1f711aff4945fe842972ee11). Otherwise, you will have problems with an incorrect number in the instrument's config area when deploying. 

doc/uncategorised/Deploy-script-workflow.md renamed to doc/deployment/Deploy-script-workflow.md

@@ -1,14 +1,10 @@
-> [Wiki](Home) > [Deployment](Deployment) > [Deploy script workflow](Deploy-script-workflow)
-
-## Deploy script location
+# Deploy script workflow
 
 Scripts needed are in: `\\isis\shares\ISIS_Experiment_Controls_Public\ibex_utils\installation_and_upgrade`
 some instruments it might want instead if not default on cclrc.ac.uk
 `\\isis.cclrc.ac.uk\shares\ISIS_Experiment_Controls_Public\ibex_utils\installation_and_upgrade`
 
-## Steps
-
-### Pre-script
+## Pre-script
 1. Use RealVNC Viewer to ensure that the instrument is not currently in use.
 1. Remote desktop into the instrument
 1. Open git-bash
@@ -18,7 +14,7 @@ some instruments it might want instead if not default on cclrc.ac.uk
     4. Ask senior team member if any of the deleted/new/modified files are of note and record the ones that are, to deal with later.
 1. Run deploy script in the tools' directory, you can double click on `instrument_deploy.bat` but it is safer to create a command window and then run the command from there, if the process were to crash you see the last message in the window. The install does now write a log file so this may not be necessary, but i usually still do it this way in case. 
 
-### During script
+## During script
 
 | Config step (in order of script) | Instruction (y/n) | Comment |
 | ----------- | ----------------- | ------- |

doc/uncategorised/Deployment-on-an-Instrument-Control-PC.md renamed to doc/deployment/Deployment-on-an-Instrument-Control-PC.md

@@ -1,22 +1,21 @@
-> [Wiki](Home) > [Deployment](Deployment) > [Deployment on an Instrument Control PC](Deployment-on-an-Instrument-Control-PC)
+# Deploy to an instrument machine
 
 This document describes the steps necessary to install/upgrade IBEX on an Instrument control PC. Be sure to login as `spudulike` when deploying on instruments instead of `gamekeeper`.
 
-# Steps using the install/deployment script
 ## Preparatory Steps for Client and Server
 
 - Inform the instrument scientist that you are going to upgrade the instrument in 5 minutes so that they are not surprised when you remote desktop to the instrument, include a link to the release notes of the latest release in this email. Wait 5 minutes.
 - Visit each instrument on which code will be released and check for changes which have been made which are not summarised on the [IBEX wiki](https://github.com/ISISComputingGroup/IBEX/wiki#tocInstrumentInfo). Do this by running `git status` in the EPICs directory and looking at the diff and comparing with those changes.
 - Make sure that the public share has the most recent version of `ibex_utils` from Git (i.e. do git pull).
 
-### Notes on network share access
+## Notes on network share access
 The install will need to access both `<public share>\ibex_utils` (where the install script is located) and `kits$` (where the ibex release and a genie python instance is kept). As we will be updating python, we cannot use the locally installed python for the deploy. 
 
 On an instrument NDX computer the D: and O: drives will be mapped to the instrument archive and have sufficient access rights, however they can sometimes become disconnected and then things don't work. So before starting look in windows explorer and if D: and/or O: are showing as Disconnected click on them to reconnect.
 
 If you do not have either a D: or O: network drive, then you will need to specify network credentials to map the drive via the `net use` command.    
 
-### Upgrading IBEX to the latest version
+## Upgrading IBEX to the latest version
 1. If an instrument, check D: network drive status as per above _Notes on network share access_
 1. Ensure the instrument is running and in a setup state
 1. Take screenshots of blocks, motors, running VIs, etc. to allow later comparison
@@ -30,7 +29,7 @@ If you do not have either a D: or O: network drive, then you will need to specif
     - Do not remove any SECI icons from the task list if this is not the first time install
 1. Compare screenshots taken earlier to current state
 
-### install IBEX for the first time
+## Install IBEX for the first time
 _Note this is unlikely to happen now we've migrated most instruments, and SECI instruments should have a copy of IBEX at the least._
 <details>
 <summary> Click to expand</summary>
@@ -44,7 +43,3 @@ _Note this is unlikely to happen now we've migrated most instruments, and SECI i
 - If needed, shutdown IBEX and [upgrade the ISISICP](Upgrade-ISISICP). Remember to run the journal parser installation (Step 8 of upgrading ICP) - this can take some time.
 - After the script has successfully finished and the IBEX server has been started, run `instrument_test.bat` in the same folder and follow the instructions.
 </details>
-
-# Manual deploy instructions
-
-Moved to https://github.com/ISISComputingGroup/ibex_developers_manual/wiki/OLD-Manual-deployment-instructions-(not-for-normal-use)

doc/uncategorised/IBEX-Deployment-on-Training-machine.md renamed to doc/deployment/IBEX-Deployment-on-Training-machine.md

@@ -1,4 +1,4 @@
-> [Wiki](Home) > [Deployment](Deployment) > - [How to deploy IBEX to training machine](IBEX-Deployment-on-Training-machine)
+# Deploy to a training machine
 
 Training machines have there own deployment script. It is similar but not the same as the usual instrument upgrade/deployment. It removes all previous traces of IBEX on the system and then installs it as if it was a clean machine. It also installs some training material and a training config.
 

doc/deployment/Installing-and-Upgrading-MySQL.md

@@ -0,0 +1,17 @@
+# MySQL
+
+## Installation
+
+Follow the steps set out in [upgrade mysql to version 8.0](https://github.com/ISISComputingGroup/ibex_developers_manual/wiki/Upgrading-to-MySQL-8), skipping the step to uninstall MySQL 5.7 if this is a first time install as opposed to an upgrade.
+
+## Troubleshooting
+
+### The installer is complaining that it needs a new version of the .NET framework
+
+This may just be an issue with the installer rather than with MySQL itself. There is a workaround that lets you avoid having to install a new .NET framework:
+1. Use an installer for an older version of MySQL
+1. Once complete, run the MySQL Community Installer from the start menu
+1. Click on the "Catalog..." button. Follow the prompts to download the latest MySQL product catalog.
+1. Once that is done, click on the "Upgrade" button on the MySQL installer home page. Here you can manually select the version you would like to install.
+
+```

doc/uncategorised/Making-an-Instrument-Available-from-the-GUI.md renamed to doc/deployment/Making-an-Instrument-Available-from-the-GUI.md

@@ -1,4 +1,4 @@
-> [Wiki](Home) > [Deployment](Deployment) > [Making an Instrument Available from the GUI](Making-an-Instrument-Available-from-the-GUI)
+# Adding an instrument to the instrument list
 
 The new instrument must be added to the list of available instruments so that users can control it from the Ibex GUI. The list of available instruments is stored in a PV called `CS:INSTLIST`, which runs on the beam status IOC, and is therefore independent of any specific instrument.
 
@@ -26,7 +26,7 @@ To add a new instrument to this list proceed as follows:
 1. Verify that all the instruments are picked up by the GUI (e.g. there are no parsing errors): `IBEX -> Switch Instrument` and that they have the correct alarm server and configuration loaded.
 1. Verify that the web dashboard for the instruments still works
 
-# Restricting the GUI to switching to a reduced set of instruments
+## Restricting the GUI to switching to a reduced set of instruments
 On the IDaaS machines we need to be able to limit the instruments that a user can switch to in the GUI, to protect the data of other users. This is performed by adding a whitelist to the instrument preferences supplier. This needs to be applied for each VM group that needs to be restricted.
 
 This shouldn't get overwritten during the RPM deploy as the preferences folder is created by the GUI when it first starts, and isn't in the build.

doc/uncategorised/testing/Manual-System-Tests.md renamed to doc/deployment/Manual-System-Tests.md

@@ -1,4 +1,4 @@
-> [Wiki](Home) > [Deployment](Deployment) > Manual system tests
+# Manual system tests
 
 Manual system tests should be performed as part of the release cycle and should be performed once a branch has been created. See [Creating-a-release](Creating-a-release)
 

doc/processes/Modifying-Code-on-an-instrument.md renamed to doc/deployment/Modifying-Code-on-an-instrument.md

@@ -1,14 +1,14 @@
-> [Wiki](Home) > [Deployment](Deployment)
+# Patching a deployed client
 
 If you need to modify a plugin on an IBEX client running on an instrument, such as OPIs, you need to go to 
 
 ```<installed client dir>/plugins/<whichever plugin you're interested in>```.
 
-# Live editing opis / non-compiled code
+## Live editing opis / non-compiled code
 
 These can be edited on the fly. If you edit a `.opi` file, the change will be seen the next time the opi is opened in IBEX. However, if you edit `opi_info.xml` (for example, to add an entirely new opi) you will need to relaunch the client as this file is only read once at startup.
 
-# Live editing "compiled" code
+## Live editing "compiled" code
 
 Plugins can be built as either folders containing `.class` files, or `.jar` files. If you need to edit the contents of a `.jar`:
 - Rename the plugin from `_.jar` to `_.zip`

doc/processes/Modifying-Device-on-an-Instrument.md renamed to doc/deployment/Modifying-Device-on-an-Instrument.md

@@ -1,10 +1,9 @@
-> [Wiki](Home) > [Deployment](Deployment) > [Mount or create IBEX VHDs](Mount-or-create-IBEX-VHDs)
-
-# Deployment
+# Mount or create IBEX VHDs
 
 The new architecture for deployment is to deploy onto VHDs which will be copied to the desired places and linked in; this was a result of [discussions of making deployment quicker](Plan-how-to-deploy-automatically-on-30-instruments).
 
-## Part of the system
+## Parts of the system
+
 ### System VHD
 
 There needs to be a system VHD, this has been created by Chris and will be detailed *CHRIS TODO*. This contains windows and user level programs (probably including labview).
@@ -26,15 +25,15 @@ These contain part of the system which change often. We are undecided what to do
 
 For the test system I have gone with the first approach because it was easy. I like the second approach better.
 
-# VHD Creation
+## VHD Creation
 
-## Create empty VHDs
+### Create empty VHDs
 
 1. Copy the three empty vhdx files (`empty_apps.vhdx`, `empty_var.vhdx`,`empty_settings.vhdx`) to a local disk (from CompGroup\chris) and rename to
 `apps.vhdx`, `var.vhdx` and `settings.vhdx`.
 2. These are pre-configured to be 30GB each.
 
-## Mount a VHD
+### Mount a VHD
 
 1. Open a command prompt as administrator
 1. `diskmgmt.msc`
@@ -45,15 +44,14 @@ For the test system I have gone with the first approach because it was easy. I l
   1. Mount `Settings.vhdx` to `C:\Instrument\Settings\config` as above
   1. Mount `Var.vhdx` to `C:\Instrument\var` as above
 
-## Dismounting VHD
+### Dismounting VHD
 
 1. Close the VHD and copy back
     1. Right click on drive on left at the bottom
     1. Detach VHD
     1. Copy file back to the source
 
-# VHD Creation Jenkins Job
-## 
+## VHD Creation Jenkins Job
 
 There is an [automated job in jenkins](http://epics-jenkins.isis.rl.ac.uk/job/Create_VHD/) which builds VHDs from the latest IBEX server/client/python versions.
 
@@ -87,7 +85,7 @@ Once filled with IBEX files, the VHDs are copied to:
 \\isis\inst$\Kits$\CompGroup\ICP\VHDS
 ```
 
-# Upgrade IBEX Version on a VM By Copying VHD
+## Upgrade IBEX Version on a VM By Copying VHD
 
  - The VM set up, running an older version of IBEX, has been located within Hyper-V manager.
  - If you wish, a 'Checkpoint' (Right Click -> Checkpoint) can be capture of the current system to allow a way to restore the VM to a functioning state, if required.

doc/uncategorised/Modifying-Plugins-on-a-Deployed-Client.md renamed to doc/deployment/Modifying-Plugins-on-a-Deployed-Client.md

@@ -1,4 +1,4 @@
-> [Wiki](Home) > [Deployment](Deployment) > [NPort Install](NPort-install)
+# Moxa NPort
 
 To install/upgrade NPort driver:
 

doc/uncategorised/Mount-or-create-IBEX-VHDs.md renamed to doc/deployment/Mount-or-create-IBEX-VHDs.md

@@ -1,4 +1,4 @@
-> [Wiki](Home) > [Deployment](Deployment) > [How to release a single IOC to an instrument](Release-Single-IOC)
+# Release a single IOC
 
 We may want to release a single IOC to an instrument but not release a whole build. This is the procedure to do this:
 

doc/uncategorised/NPort-install.md renamed to doc/deployment/NPort-install.md

@@ -1,4 +1,6 @@
-### Once a deploy has been finished and the ticket requires a review the following tasks should be done to review the ticket:
+# Reviewing deploy tickets
+
+Once a deploy has been finished and the ticket requires a review the following tasks should be done to review the ticket:
 
 - Connect to the machines deployed to and check the current versions of the GUI and server. (In the gui select about, the GUI and Server version numbers should be listed).
 - Check that any hotfixes have appropriate tickets.

doc/uncategorised/Release-Single-IOC.md renamed to doc/deployment/Release-Single-IOC.md

@@ -1,10 +1,10 @@
-> [Wiki](Home) > [Deployment](Deployment) > [Updating Instrument Machines](Updating-Instrument-Machines)
+# Updating an instrument machine (email templates)
 
 It is important to remember when making any changes to instruments (e.g. installing new IBEX versions, cleaning disk space etc) that they are in (potentially) constant use by the instrument scientists and so they must be properly informed. Below is a template of what to send to scientists, this should be sent from the Experiment Controls email account.
 
 If only a subset of instruments are being modified lookup the instrument scientists for these instruments [here](https://www.isis.stfc.ac.uk/Pages/Instrument-Scientists.aspx) and email only those affected. If most instruments are going to be modified then email the ISIS Instrument Scientists + Others.
 
-## A New Release
+## New Release
 
 For a new release of IBEX the following should be sent as soon as possible, at least a week (ideally 2 weeks) before the deployment date:
 
@@ -23,7 +23,7 @@ Thanks,
 ISIS Experiment Controls
 ```
 
-## A Hot-fix
+## Hot-fix
 
 In this context a hot fix refers to any modification of an instrument machine that needs to be done at somewhat short notice e.g.:
 * Patching a critical bug in some code