Merge pull request #75 from gridpp/troubleshooting-guide-001

Adding a troubleshooting section.

Author: Tom Whyntie

SUMMARY.md

@@ -40,6 +40,8 @@ Welcome to the [GridPP](https://www.gridpp.ac.uk) UserGuide.
 
 * [What's Next?](whats-next/whats-next.md)
 
+* [Troubleshooting](troubleshooting/troubleshooting.md)
+
 * [Appendix: Creating a GridPP CernVM User Interface](gridpp-cernvm/gridpp-cernvm.md)
     * [Checklist](gridpp-cernvm/checklist.md)
     * [Testing](gridpp-cernvm/testing.md)

before-we-begin/getting-help.md

@@ -5,6 +5,14 @@ _GridPP UserGuide_.
 If you don't happen to have a GridPP expert in the office
 down the corridor, you can try the methods described below.
 
+##Check the troubleshooting guide
+We've added a
+[short troubleshooting guide](../troubleshooting/troubleshooting.md)
+for problems that users have come across that we know are specific
+to particular systems, generally raised via the
+[GitHub Issues page](http://github.com/gridpp/user-guides/issues).
+It might be worth checking here first for anything obvious.
+
 ##Googling the error
 We can't possibly account for every error a user might
 encounter when working through the _UserGuide_,

example-workflow-grid/example-workflow-grid.md

@@ -90,9 +90,26 @@ DiracEnvSource = /cvmfs/ganga.cern.ch/dirac_ui/bashrc
 
 [defaults_DiracProxy]
 group = <dirac user group>
+
+[defaults_DiracFile]
+defaultSE = <your SE of choice>
 ```
 where `<dirac user group>` should be replaced by your
-default VO (e.g. `gridpp_user`).
+default VO (e.g. `gridpp_user`)
+and
+`<your SE of choice>` should be replaced by a suitable
+Storage Element, e.g. `UKI-LT2-QMUL2-disk`.
+
+<table>
+<tr>
+<td align='center'><i class="fa fa-lightbulb-o" style='font-size:3em'></i></td>
+<td>
+You can find a list of Storage Elements names by using the
+<code>dirac-dms-show-se-status</code> command from the command line.
+</td>
+</tr>
+</table>
+
 You can then re-start Ganga; it will now be ready to connect
 to the DIRAC backend.
 

troubleshooting/troubleshooting.md

@@ -0,0 +1,44 @@
+#Troubleshooting
+This section contains brief notes on specific problems users have
+encountered when working on specific systems,
+generally raised via the
+[GitHub Issues page](http://github.com/gridpp/user-guides/issues).
+
+##Ganga
+_Ganga isn't working._
+
+If you're having problems with Ganga, the best thing to do is to
+[raise an issue](https://github.com/ganga-devs/ganga/issues)
+with the Ganga dev team through the
+[GitHub repository](https://github.com/ganga-devs/ganga/).
+At the time of writing,
+we've been using Ganga version 6.3.1 - but as Ganga is under
+active development this may change so you may want to
+[watch the repository too](https://github.com/ganga-devs/ganga).
+
+_Ganga throws errors relating to not being able lock files._
+
+If the file system your cluster is based on can't handle
+(or hasn't been set up to allow)
+file locks, which Ganga uses.
+If your home directory is on such a file system
+(e.g. NFS),
+files in your `~/gangadir` won't be lockable and Ganga won't work.
+Assuming your cluster can't be reconfigured, the simplest thing to
+do is change the location of your `gangadir` to somewhere that
+can handle file locks, such as a scratch directory on the cluster.
+To do this, set the `gangadir` option in `~/.gangarc` to something like:
+
+```bash
+gangadir = /scratch/alovelace/gangadir
+```
+
+and restart Ganga in the usual way.
+
+_My problem isn't listed here and search engines aren't helping either._
+
+Raise an issue on the
+[GitHub issues page](http://github.com/gridpp/user-guides/issues)
+and we'll see if we can help!
+
+Good luck!