====== Getting Started ======

This document aims to describe what is needed to get a released version of Diana up and running on Ubuntu 12.04 (Precise) from a set of Debian packages. It is assumed that you will be using the version of Ubuntu that the packages were developed for.

To build Diana for other distributions, see the [[autotools|Building Metlibs and Diana with Autotools]] page for an installation guide then continue reading the [[Installing Data Files]] page.

To build a batch version of Diana for headless systems, install ''bdiana'' according to the instructions on the [[batch_diana_on_headless_systems|Batch Diana on Headless Systems]] page then continue reading the [[Installing Data Files]] page.

===== Installing Packages =====

Obtain a set of release packages for the current release of Diana. Follow the instructions on the [[Installing Diana from Launchpad]] page to install and test the packages.

===== Configuring Diana =====

Diana expects to find a ''diana.setup'' file in various locations:

  * The current directory.
  * ''$HOME/.diana/diana.setup'' or equivalent

If you built and installed Diana 3.39 from source, or installed a package from Launchpad, there should also be a setup file in the following location:

  * ''/etc/diana/3.39/diana.setup''

If you installed the maps and demo data in a location other than the default,
you will need to change the ''OPDATA'' and ''MAPDIR'' lines in the ''diana.setup''
file. For example, if these resources were unpacked in the ''/data/diana''
directory, these lines need to be changed to read:

<code>
OPDATA    = /data/diana/demodata
MAPDIR    = /data/diana/maps
</code>

This means that you need to have a ''diana.setup'' file in a place where you can
edit it. Possibly the easiest way to arrange this is to run Diana without a ''diana.setup''
file then immediately quit. This will cause the ''.diana'' directory to be created
in the user's home directory. Then copy the ''/etc/diana/3.39/diana.setup'' file
(or the correct one for the version you are using) into that directory for further
configuration.

===== Testing with bdiana =====

It is useful to test that the basic installation works correctly, particularly on headless systems that only allow ''bdiana'' to run. Copy the following text into a file called ''test.input'':

<code>
buffersize=800x800
output=PNG
filename=test.png

PLOT
MAP backcolour=117:199:242 map=Gshhs-Auto contour=on cont.colour=black cont.linewidth=1 cont.linetype=solid cont.zorder=1 land=on land.colour=240:158:92
AREA proj4string="+proj=ortho +lat_0=60" rectangle=-1500000.000000:1500000.000000:-1250000.000000:1750000.000000
ENDPLOT
</code>

Process the input file using a command like the following, using the appropriate executable and setup file for your configuration:

<code>
bdiana -i test.input -s diana.setup
</code>

A file called ''test.png'' should be created that looks like the following image:

{{diana:test.png?|}}

If the file is not created or the image is blank, check the output from ''bdiana'' to determine whether the ''diana.setup'' file and map files were found correctly.

You can also find more input files to test in the [[https://github.com/metno/diana-extras|diana-extras]] repository on GitHub. The files can be found in the [[https://github.com/metno/diana-extras/tree/master/testfiles/input|testfiles/input]] directory.
===== Running Diana =====

Run Diana using either the ''diana'' script or the ''diana.bin'' executable.
The ''diana'' script will try to send debug information back to the e-mail
address for bug reports. If you want to avoid this, run the ''diana.bin''
executable instead.

If you have created a ''diana.setup'' file in a location other than one of
those mentioned above then you need to pass an option on the command line
to specify where it is.

<code>
diana -s /path/to/diana.setup
</code>

The path specified must be an absolute path.