Installation
************

Compilation
-----------

To build this project, you need:

* JDK >= 1.5, make sure you use Sun's JDK (sun-java6-jdk on Ubuntu 8.04) and not GCJ
* Download MapFish Print from GitHub

  * On systems with git installed::
      
      Go to https://github.com/mapfish/mapfish-print
      Click the "Fork" button to fork a version to your user
      Assuming your username is myuser type

      git clone git@github.com:myuser/mapfish-print.git

The other external libs are taken care of by maven.

The build command to use is:

* On Linux::

    cd %MAPFISH_DIR%/trunk/
    ./gradlew build

* On Windows::

    cd %MAPFISH_DIR%/trunk/
    gradlew.bat build

You might get an error like:

.. code-block:: bash

    ....
    .....
    FAILURE: Could not determine which tasks to execute.
    
    * What went wrong:
    
    Task 'build' not found in root project 'src'.
    
    * Try:
  	
    Run with -t to get a list of available tasks.
    
    BUILD FAILED
    ....
    .....

Then try::

  cd %MAPFISH_DIR%/trunk/
  ./gradlew clean build

Print module installation
--------------------------

The PDF generation requires some code to run on your web server. This page describes how to install it.

Depending on what language/framework you want to use on your server and what performance you need, multiple solutions are available. The next sections will describe them.

In all cases, **you have to modify the print.yaml file** to customize it. At least to add the list of hosts that can be used to get the maps from.

Python
~~~~~~

1. Edit the development.ini file and add two lines like that to the [DEFAULT] section (change the strings "%....%" by something relevant)::

    print.jar = %MAPFISHDIR%/trunk/build/libs/print-standalone-%VERSION%.jar
    print.config = %PROJECT_DIR%/print/config.yaml

2. Edit the config.yaml file in your %PROJECT_DIR%/print/ directory as documented in the `Print Module Server <configuration.html>`_ page. 
3. Edit the MY_PROJECT/config/routing.py file and add those 2 lines (just after the "CUSTOM ROUTES HERE")::

    from mapfish.controllers import printer
    printer.addRoutes(map, '/print/', 'printer')

4. Create a MY_PROJECT/controllers/printer.py file with this single line as content::

    from mapfish.controllers.printer import PrinterController

5. If you use Apache mod_wsgi, you can add the following before the "loadapp" call in the WSGI script::

    # configure the logging system
    from paste.script.util.logging_config import fileConfig
    fileConfig('%PASTE_CONFIG%')

   where ``%%PASTE_CONFIG%`` is the path to the application's configuration file (.ini).

Java servlet
~~~~~~~~~~~~

This method will give you the best performance.

The separate WAR way
++++++++++++++++++++

For that you need to install tomcat5.5 or higher.

Note: some people have experienced problems when deploying the MapFish Print WAR in the Tomcat packaged in Ubuntu, it looks like these problems are due to additional security constraints in the Ubuntu package. If you have such problems and don't know how to solve them you can download Tomcat from the Apache web site, for example MapFish Print is known to work well with apache-tomcat-6.0.20.tar.gz.

In my system, tomcat is installed in **/var/lib/tomcat5.5** and the %WEBAPPS% directory is in **/var/lib/tomcat5.5/webapps**.

1. copy the WAR file in your %WEBAPPS% directory. This is can be obtained from `%MAPFISH_DIR%/trunk/build/libs/print-servlet-*.war` if you compiled the print module or you can get it from the `maven repository <http://dev.mapfish.org/maven/repository/org/mapfish/print/print-servlet/1.1/print-servlet-1.1.war>`_. 
2. Edit the config.yaml file in your `%WEAPPS%/print-servlet-*/` directory as documented in the `Print Module Server <configuration.html>`_ page. 
3. If needed, edit the web.xml and log4j.properties files. 

If your web pages are not served by the tomcat server, you may need to configure a proxy to work around the `same origin policy <http://en.wikipedia.org/wiki/Same_origin_policy>`_. See `Configure Proxy <http://trac.mapfish.org/trac/mapfish/wiki/ConfigureProxy>`_ for examples on how you may do that.

Included into another web application
+++++++++++++++++++++++++++++++++++++

If you are developping a web application, you can include the print module in it. This explanation works only if you use Maven to build your project. For others, you'll have to include the print-lib JAR file and all its dependencies.

1. Add the print-lib dependency to your WAR project by adding these two elements to your pom.xml file (adjust the version)::

        ...
        <dependencies>
          <dependency>
            <groupId>org.mapfish.print</groupId>
            <artifactId>print-lib</artifactId>
            <version>%RELEASE%</version>
          </dependency>
          ...
        </dependencies>
        ...
        <repositories>
          <repository>
            <id>geotools</id>
            <url>http://download.osgeo.org/webdav/geotools</url>
          </repository>
		  <!-- The next repository is only required if the release is a snapshot -->
          <repository>
            <id>maven snapshots</id>
            <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
            <snapshots>
				<enabled>true</enabled>
			</snapshots>
          </repository>
          ...
        </repositories>
        ...

2. Add these three sections (correct the paths and URLs in function of your needs) to your WEB-INF/web.xml file::

        ...
        <listener>
          <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
        </listener>
        <context-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>classpath:mapfish-spring-application-context.xml,classpath:*-mapfish-spring-application-context-override.xml</param-value>
        </context-param>
        ...
        <servlet>
          <servlet-name>mapfish.print</servlet-name>
          <servlet-class>org.mapfish.print.servlet.MapPrinterServlet</servlet-class>
          <init-param>
            <param-name>config</param-name>
            <param-value>config.yaml</param-value>
          </init-param>
        </servlet>
        <servlet-mapping>
          <servlet-name>mapfish.print</servlet-name>
          <url-pattern>/pdf/*</url-pattern>
        </servlet-mapping>
         ...

3. Add a config.yaml file (from the `samples <https://trac.mapfish.org/trac/mapfish/browser/print/trunk/samples>`_, for example) to the root of your web application. 

Configuring Servlet Temp Directory
++++++++++++++++++++++++++++++++++
By default the default servlet temporary directory will be used but that behaviour can be overridden setting the init-param *tempdir*.  If this parameter is set the servlet must have write access to the directory.

Command line
~~~~~~~~~~~~

For debugging or calling from other environments, you can run the print module from the command line.

Examples are assumed to be ran from the directory %MAPFISHDIR%/server/java/print.

The fastest way is to call to gradle to run the application.  

.. code-block:: java

  ./gradlew run -Dconfig=samples/config.yaml -Dspec=samples/spec.json -Doutput=/tmp/print-out.pdf

Help about the command line's option can be obtained like that:

.. code-block:: java

./gradlew run

If you have previously built you can run the existing jar using the following commands:

.. code-block:: java

  java -Djava.awt.headless=true -cp build/libs/print-standalone-%VERSION%.jar org.mapfish.print.ShellMapPrinter --config=samples/config.yaml --spec=samples/spec.json --output=$HOME/print.pdf

Help about the command line's option can be obtained like that:

.. code-block:: java

  java -Djava.awt.headless=true -cp build/libs/print-standalone-%VERSION%.jar org.mapfish.print.ShellMapPrinter
  

With Image output line
~~~~~~~~~~~~~~~~~~~~~~

At the moment to have robust image (png, gif, etc...) output options the image magick command line tool must be used.  The tool is cross platform and available on linux, windows and mac osx.  Before installing mapfish print first install both:

 * ImageMagick (specifically ensure that the convert tool has been installed)
 * Ghostscript

Once ImageMagick is installed (and Ghostscript) then the spring configuration needs to be updated so that org.mapfish.print.output.NativeProcessOutputFactory object will be used as an option for creating output files.  This OutputFactory uses native commandline processes for converting a PDF to an alternate format. The mapfish-spring-application-context.xml can be directly edited to configure the OutputFactory or the file https://github.com/mapfish/mapfish-print/blob/master/sample-spring/imagemagick/WEB-INF/classes/imagemagick-spring-application-context-override.xml can be copied into the mapfish-print/WEB-INF/classes folder (if a servlet is being used).  
 
Since the ImageMagick support is a commonly requested configuration there is an IMAGEMAGICK artifact prebuild with the correct configuration.  To use this artifact change your maven dependency from: print-servlet-1.2-SNAPSHOT to print-servlet-1.2-SNAPSHOT-IMG-MAGICK (you will likely have to change the 1.2-SNAPSHOT portion to the version of mapfish that you are using).

By default ImageMagick will try to find the convert tool in /usr/bin/convert.  You will want to find the path to your convert tool and update imagemagick-spring-application-context-override.xml if that file is included in your build, or mapfish-spring-application-context.xml if you manually changed the mapfish-spring-application-context.xml file to include the imagemagick configuration.