I’m not Scaramanga (maybe a little bit of Nick Nack) but anyway, this article could be be a golden bullet for helping you to eliminate a lot of obstacles if you are using QGIS in some kind of class-room setup, networked environment and/or are struggling with the “new versions 3 times a year” policy of QGIS.

man-with-the-golden-gun-008

My interest for a hassle free and fast installation of QGIS stems from an experience last year: Some colleagues and I was giving a QGIS workshop for attendants from all over the world. We were told that QGIS was installed on all the computers in the “out-of-town” computer lab and indeed, the computers we checked had a working installation of QGIS. Next day, 15 minutes before the workshop should start, we discovered that the QGIS installations was either non-existent or badly mangled on a large portion of the rest of the computers. And no person with “local admin” rights within sight. It would be an understatement to say that the first hour of the workshop was an interesting time for us. Well, all’s well that ends well, and in the end the workshop was a success (Lucky us!)

A couple of months later I stumbled on this article “A QGIS class room setup on Windows ” – thanks to Richard Duivenvoorde – and tried the setup by copying the qgis program directory from the initial install to another “clean” computer. Alas, QGIS did work on some – but not on all of the computers, I tried it on. The QGIS installation had some dependencies to dll’s in the windows/system32 directory. If they already were present, the “copy” installation would work but otherwise it would fail. I discovered a somewhat complicated solution to the problem and publicized it in the article “How to make a ‘QGIS on a stick’ implementation”

Then, some weeks ago at the “QGIS 2015 conference at Nødebo“, I had a chat with QGIS core developer Jürgen E. Fischer about my installation problems and viola! Two days after the chat, the OSGEO4W network installation contained the missing dll’s, Thanks Jürgen.

So now we have two bits of information:

  • By using the “–configpath” qualifier we can redirect where QGIS is looking for plugins, user selected values for options, values and files normally saved in the .qgis2 directory or in the registry.
  • The OSGeo4W network installation creates QGIS without any dependencies to external dll’s outside the installation directory. You could make an installation by simply copy an existing QGIS program directory to another computer.

This gives us some interesting possibilities:

  • Use case I : “QGIS on a stick”
    You can make a QGIS installation located on a memory stick and completely self contained; simply plug in the stick into a Windows computer and start QGIS by double clicking on the QGIS startup file.
  • Use case II: “Simple ‘xcopy’ installation of QGIS”
    Make an installation procedure for QGIS that consists of a simple copy of the QGIS program directory to a new computer. Like the answer to: “How the heck am I going to install QGIS on 24 computers in half an hour ?”
  • Use case III: “Network install of QGIS with floating profiles”
    Install QGIS on a network file share and put the QGIS setup information into the “Floating profile”. A large part of a user profile including will be cached on a central server in the windows domain. If the user logs on to another computer than the usual, his/her profile will automatically be copied to the new computer, giving the user his “normal” desktop and setups.
  • Use case IV: “QGIS on Citrix”
    Normally it ain’t my cup of tea to install any kind of program on a Citrix server where the program has a “canvas” area with fast changing images/pixels. For example: A GIS program like QGIS showing a map with an orthofoto background with millions of pixels – all with a slightly different hues of greens or browns.
    However, many IT departments swears by Citrix, so….
  • Use Case V: “Smart installation and update of a large amount of QGIS installations”
    If you have to install QGIS on dozens or hundreds of computers and keep the installation up-to-date, this is the use-case for you.

Step 1: Creating the common template..

First you have to create a common template for your future installation(s) whatever use case you implement afterwards. I use the 32-bit edition of the network installation as a basis for this although it’s perfectly possible to use the 64 bit version.

  1. Browse to http://qgis.org/en/site/forusers/download.html and click on OSGeo4W Network installer (32 bit) . This will download the installer.
  2. Start the installer and choose “Express Desktop Install”.
  3. Check “QGIS” and uncheck everything else.
  4. Check “I agree yadda yadda…” to every license message.This will install a default QGIS installation in directory C:\OSGeo4W and create a QGIS user directory in C:\Users\<my username>\.qgis2, i.e. the directory .qgis2 in your home directory. These 2 directories is the basis for the template. You can check the installation by starting QGIS from the “OSGeo4W” program group in “Start” –> “All Programs”. It should work without problems.
  5. Copy the C:\Users\<my username>\.qgis2 directory with contents to C:\OSGeo4W, so you’ll have a C:\OSGeo4W\.qgis2 directory.
  6. Copy the startup file for QGIS: C:\OSGeo4W\bin\QGIS.bat to C:\OSGeo4W\bin\QGIS.ref. This is insurance ! If you utterly mangle QGIS.bat in the next steps you have this file as a backup. Otherwise you are not going to use it for anything.
  7. Edit the file: C:\OSGeo4W\bin\QGIS.bat with a simple text editor like notepad.
    Insert 2 lines between line 2 and 3 in the bat file:

    call “%~dp0\o4w_env.bat”
    call “%OSGEO4W_ROOT%”\apps\grass\grass-6.4.4\etc\env.bat

    so it looks like this:

    call “%~dp0\o4w_env.bat”
    set QGIS_OAS=”%OSGEO4W_ROOT%”\.qgis2
    if exist “%OSGEO4W_ROOT%”\bin\QGIS_OAS.bat call “%OSGEO4W_ROOT%”\bin\QGIS_OAS.bat
    call “%OSGEO4W_ROOT%”\apps\grass\grass-6.4.4\etc\env.bat

    and replace the last line in the bat file:

    start “QGIS” /B “%OSGEO4W_ROOT%”\bin\qgis-bin.exe %*

    with this line:

    start “QGIS” /B “%OSGEO4W_ROOT%”\bin\qgis-bin.exe –configpath %QGIS_OAS% %*

    and save the result.

    What the edits mean:

    • Create an environment variable %QGIS_OAS% which works as a pointer to the location of the .qgis2 directory. Initially it points to the .qgis2 directory inside the OSGeo4W installation directory we created in (5).
    • Execute a command-file “QGIS_OAS.bat” if it exists. This command-file is the basis for all our different use-cases. There will be a different version for each use-case. Initially we don’t use this file.
    • Add the “–configpath %QGIS_OAS% qualifier to the actual start of QGIS. This means, that QGIS will look for all setup information, user-defined options, plugins and whatnot in the directory specified by the %QGIS_OAS% environment variable. And QGIS will not use any settings in the registry.
  8. Start QGIS by double clicking the revised C:\OSGeo4W\bin\QGIS.bat file and make all the changes to the initial setup of QGIS that should be included in your future QGIS installation(s). This could be change of language, default projection, extra plugins, snap options, yadda yadda yadda. Come on, make you dream QGIS setup !!

Thanks to the –configpath qualifier now on the start line for QGIS all these changes will be saved in the C:\OSGeo4W\.qgis2 directory. After this, you have a complete setup of QGIS – with your own changes – all located in the C:\OSGeo4W directory. This is the common template for all use cases.

Step 2: Do one of the use cases…

Use case I : “QGIS on a stick “

You have already done this use case. The template made in step 1 is a ready made “QGIS on a stick” installation:

  1. Copy the entire C:\OSGeo4W template directory from your computer to the root of your memory stick.
  2. Insert the memory stick into any Windows computer and start QGIS by double clicking on \OSGeo4W\bin\qgis.bat on the memory stick.
    QGIS will use \OSGeo4W\.qgis2 on the memory stick as the QGIS user directory.

Use case II : “Simple ‘xcopy’ installation of QGIS “

In this use case we will have to extend the template by creating the QGIS_OAS.bat file. This example will put the QGIS user directory “.qgis2” in the users home directory, just like the normal installation does – with one exception: This installation will not use the registry but save all user options in a ini-file placed in the QGIS user directory.

  1. Create the file C:\OSGeo4W\bin\QGIS_OAS.bat with the following content:
    set QGIS_OAS=”%USERPROFILE%”\.qgis2
    if exist %QGIS_OAS% exit /B
    xcopy “%OSGEO4W_ROOT%”\.qgis2 %QGIS_OAS% /e /i
    nircmd shortcut “””%OSGEO4W_ROOT%””\bin\qgis.bat” “~$folder.desktop$” “Start QGIS” “” “””%OSGEO4W_ROOT%””\bin\qgis-bin.exe” “0” “min” “””%OSGEO4W_ROOT%””\bin” “”

    (First the pointer to the QGIS user directory is changed to the “users home directory”\.qgis2. Secondly, The command file will check if the QGIS user directory exists in the users home directory. If it doesn’t exist, the command file will create a copy of the QGIS user directory template into the users home directory; create a shortcut to start QGIS and place this shortcut on the user’s desktop.)

  2. You can now install QGIS on a new PC by copying the entire C:\OSGeo4W directory to the new pc (using a memory-bird, network drive, zip-copy-unzip, whatever). The directory can be copied to any directory location on the new PC. Please note that some locations will require “local admin” rights for creating the new directory, for example if you copy it to “C:\Program Files”. I usually try the avoid this.

First time use on the new pc:

  • Start QGIS by double clicking on C:\OSGeo4W\bin\qgis.bat (or wherever you placed the OSGeo4W directory). When QGIS starts, the combined command files QGIS.BAT and QGIS_OAS.BAT will automatically create the QGIS user directory on the new pc; create a shortcut to QGIS on the user desktop and start QGIS.

After that you can start QGIS by double clicking on the shortcut placed on the desktop.

 

Use case III: “Network install of QGIS with floating profiles ”

This usage scenario will have the QGIS installation located in a directory on a common network file-share. A normal user need only to have read and execute rights to this directory. The QGIS user directory will be placed in the users “roaming profile” on the client PC, a special region which is cached to a central server.

The computers and users are members of a AD domain. If the user logs on to another pc in the domain, the “roaming profile”, including the desktop and the QGIS user directory, will automatically be copied the new computer and the user will see the usual desktop and applications.

With this setup, there is no dependencies to any particular client pc after the first start of QGIS by the user. If the user logs on any other client PC in the domain it will be possible for her to start QGIS simply by double clicking on the QGIS shortcut on desktop.

There is some requirements: The user has to have access to the common file share (!) and the network connection has to be stable and relatively fast.

In this use case we will do the following:

  1. Copy the QGIS directory C:\OSGeo4W to the common share: X:\QGIS\Current (The drive letter X: is arbitrary; it could be any drive letter). I will explain the naming scheme of the directory later.
  2. Create the file X:\QGIS\Current\bin\QGIS_OAS.bat with the following content
    set QGIS_OAS=”%APPDATA%”\.qgis2
    if exist %QGIS_OAS% exit /B
    xcopy “%OSGEO4W_ROOT%”\.qgis2 %QGIS_OAS% /e /i
    nircmd shortcut “””%OSGEO4W_ROOT%””\bin\qgis.bat” “~$folder.desktop$” “Start QGIS” “” “””%OSGEO4W_ROOT%””\bin\qgis-bin.exe” “0” “min” “””%OSGEO4W_ROOT%””\bin” “”

    (First, The QGIS_OAS environment variable points to the qgis user directory in the roaming profile. Secondly, the command file will check if the QGIS user directory exists. If it doesn’t, the command file will copy the QGIS user directory template to the users roaming profile; create a shortcut to start QGIS and place this shortcut on the user desktop.)

First time use on the new pc:

  • Start QGIS by double clicking on X:\QGIS\Current\bin\qgis.bat. When QGIS starts, the combined command files QGIS.BAT and QGIS_OAS.bat will automatically create the QGIS user directory on the new pc, create a shortcut on the user desktop and start QGIS.
  • After the first time you start QGIS by double clicking on the shortcut placed on the desktop.

Oh .. and why did I use this particular naming scheme for the directory ? It is used to make it easy to update QGIS:

When you have a new version of QGIS, do the following:

  1. Make a template of the new qgis version as described in step 1 and use case III, but in another directory: X:\QGIS\Testing and leave the X:\QGIS\Current unchanged.
  2. Test the new installation. You might even let some of your users test it!! You can start the “testing” version of QGIS by double clicking on X:\QGIS\Testing\bin\qgis.bat
  3. When you are satisfied with the new installation:
    • Rename the directory X:\QGIS\Current to X:\QGIS\Deprecated
    • Rename the directory X:\QGIS\Testing to X:\QGIS\Current 

After the last rename operation all the networked users will execute the new version using their existing shortcut. This method will probably work with all minor updates (2.8 -> 2.10), but probably not with a major update (2.10 -> 3.0)

Use case IV : “QGIS on Citrix “

If you have a Citrix environment you probably have a personal network-based share for each an every user on the domain. For this use case I call this directory M:\Personal. But the naming convention can be anything.

The idea is to place the QGIS user directory on the personal network share, so there won’t be anything saved or registered on the Citrix server that’s user related:

Do the following:

  1. Create a working installation of QGIS on the Citrix sever using the techniques described in Step 1.
  2. Create the file C:\OSGeo4W\bin\QGIS_OAS.bat on the Citrix server with the following content:
    set QGIS_OAS=M:\Personal\.qgis2
    if exist %QGIS_OAS% exit /B
    xcopy “%OSGEO4W_ROOT%”\.qgis2 %QGIS_OAS% /e /i

    (First, The QGIS_OAS environment variable points to the qgis user directory placed on the users personal network share. In this case “M:\Personal”. Secondly, the command file will check if the QGIS user directory exists. If it doesn’t, the command file will copy the QGIS user directory template to the users personal network share.)

  3. Create the usual application startup definition for Citrix pointing to C:\OSGeo4W\bin\QGIS.bat on the Citrix server.

Bingo ! That’s it. I’ll leave the last use case “Smart installation and update of a large amount of QGIS installations” to a separate article, because it is more complicated than any of the previous use cases. I’ll try to publish that article in a week or so, so stay tuned !!

This article has a zip file “QgisOnAStick.zip” attached. It contains the revised QGIS.BAT file plus all the different types of QGIS_OAS bat files described in the article. The suffix is renamed to “.usecase_1”, “.usecase_2” and so on. Download the zip file and rename the suffix to “.bat” on the files you’re going to use.

A final note: I’ve used QGIS 2.8.2 in my tests. So the use cases works for this version of QGIS and will probably work for other QGIS 2.x versions.

Regardsbo

Bo Victor Thomsen

[email protected]
AestasGIS
Denmark

by qgisdk at 12:44 PM under articles in english , blog , installation , qgis , vejledninger , windows (Comments)