- Will be replaced with the ToC, excluding the "Contents" header {:toc}
This documentation is aimed at IT staff within organisations who wish to host and use Marxan Web within their organisation. It covers the architecture, installation, configuration and security and maintenance. If you just want to use Marxan Web without hosting it yourself, then you can simply use a hosted service which requires no installation. For more information see Migration Guide - Which should I choose? A hosted service or hosted within my organisation.
The Marxan Web software comprises a set of discrete components that work together in a network to provide the tools to do systematic conservation planning. This section outlines how these components work together and what the options are for deploying and using Marxan Web in your organisation.
Marxan Web comprises software running on a server (marxan-server) and software running on the client (marxan-client). These two separate bits of software work together in a loosely-coupled way through web services with the marxan-server providing the data storage and processing layer and marxan-client providing the user interface to that content (running in a browser). For more information on the architecture for each of these bits of software, see the relevant GitHub repos.
These two separate components can be installed on a local, network or cloud-based machine, either on the same machine or on different machines. These different options are shown in the following sections.
In a single machine installation, both marxan-server and marxan-client are installed on the same physical machine. Marxan Web is cross-platform and this is typical of a Windows installation on a desktop computer or a Unix installation on a network machine. For more information on installing on Windows, see Windows. For more information on installing on Unix, see Unix.
The marxan-server and marxan-client software can also be installed on separate machines, although this is less common and requires some additional configuration. The main advantage is that the client can then link to other installations of marxan-server.
Wherever Marxan Web is installed, when it is run the login screen shows a list of marxan-servers that are available and that you can connect to. These have been registered in the Marxan Registry and these are essentially instances of marxan-server that organisations are hosting and want to make public and share. Any organisation can register their own instance of marxan-server and can control whether it is read-only or read-write and from which domains. For more information see CORS restrictions and ENABLE_GUEST_USER. To register your organisation in the Marxan Registry contact: andrew.cottam@ec.europa.eu.
Marxan Web is cross-platform which means that it will install and run on any operating system (although there may be some slight differences in the support on different platforms). Instructions for installing on different operating systems are given below.
A Windows installer is available for installing Marxan Web on Windows and is available from the Windows Releases{:target="_blank"} page. Once downloaded, when you run the installer you can choose whether to install Marxan Web with a new PostGIS database or use an existing one:
If you want to use an existing PostGIS database, then untick the PostGIS checkbox and enter the connection information on the following page. The user must have superuser permissions.
Once the installation has completed, you can run Marxan Web from the Start Menu:
For uninstall information, see the Windows Releases{:target="_blank"} page.
marxan-server and marxan-client have to be installed separately on Unix operating systems. For more information on installing these, see the relevant GitHub repos: marxan-server and marxan-client.
The installation of Marxan Web on Mac operating systems has not been done yet as there are some issues with installing PostGIS which is a prerequisite of marxan-server.
There are various ways that marxan-server can be configured from overall settings that apply at the server level, such as database connections, security settings and access control, to settings at the user level. In a normal installation none of this configuration needs to be done, but there are a few basic steps that will increase the security of your installation. This section describes how to do that.
Configuration in marxan-server is done through a set of configuration files that are installed in the marxan-server folder and sub-folders. The following configuration files are used:
- server.dat - provides overall configuration for the marxan-server instance (in the root folder)
- user.dat - provides options for each registered user (in each users folder)
- runlog.dat - provides a log of all of the runs that have been done in the marxan-server instance (in the root folder)
These files are described in the following sections.
The server.dat file contains settings that apply at the server level. These settings are described in the following sections. If any of the settings in the server.dat file are changed, then the marxan-server will need to be restarted for those changes to take effect. For more information see Starting/stopping marxan-server.
This value is set using the Marxan Web application but it can also be set directly in the server.dat file. For more information see User Guide - Enabling Guest Users.
If this instance of marxan-server has been registered in the Marxan Registry, then you can set this value to override the server name that is in the Marxan Registry. This name will appear in the list of Marxan Servers when the login page is shown in Marxan Web.
If this instance of marxan-server has been registered in the Marxan Registry, then you can set this value to override the server description that is in the Marxan Registry. This description will appear in the list of Marxan Servers when the login page is shown in Marxan Web.
This value is used to encrypt all cookies that are exchanged between marxan-server and marxan-client and therefore if the default value is not changed then potentially malicious hackers could intercept and decode cookies to try to gain illegal access.
This is a list of domains that are allowed to access services from marxan-server to prevent Cross-Origin Resource Sharing vulnerabilities. For more information see CORS restrictions. To allow read-write access from a specific domain, append the domain to the list of existing domains (separated by a comma). Domains not on this list will only have read-only access.
If you want to connect to a different database then set the database configuration information in the relevant settings.
The location of an digital certificate file (*.crt) used with a web browser to provide SSL authentication (i.e. https). CRT files are used to verify a secure website's authenticity, distributed by certificate authority companies such as GlobalSign, VeriSign and Thawte. The full certificate chain needs to be within the certificate file.
If you get an error 'SEC_ERROR_UNKNOWN_ISSUER' in Firefox it is because the crt certificate does not include the full chain of certificates. To fix this, copy the *.crt certificate and paste it into the top of the full *.ca-bundle certificate and save this as a new certificate, e.g. certificate_chain.crt. It should then work in Firefox.
This is the location of a private key for this machine that is used with the certificate file to provide SSL authentication. Reference a private key file (*.key).
This is the port that Tornado is listening on for requests and in the default server.dat file it is set to 8080. If this is set to a non-default value and this instance of marxan-server has been registered in the Marxan Registry, then make sure that the host value in the Marxan Registry includes the correct port in the host, e.g. andrewcottam.com:8081. Be aware that some organisation firewalls block traffic over non-standard ports, e.g. ports other than 8080, so it is safest to leave this with the default value of 8080.
This is a text string that contains the version date for the WDPA that is included in the PostGIS database, e.g. August 2019. If there is a new version of the WDPA available (the information on the latest version of the WDPA is contained in the Marxan Registry), then admin users will be able to update to the latest version in the Server Details dialog box. For more information see User Guide - Server Details.
When creating planning grids, this is the threshold for the number of planning grid units that can be created. If there are more than this number, then an error message will be returned to the client.
Setting this to True will disable all security on the server. This can be useful for testing.
Set to True to disable all logging to file.
Set to True to enable a server reset. A server reset will reset a Marxan Server instance to the original install condition, including restoring the original database and removing all users. This is useful for resetting data before running a training course.
The user.dat file is used to manage user settings in Marxan Web and most of the settings are managed in the Marxan Web application. However, they can be set manually if there are issues with a users settings.
The name of the last project that the user loaded.
A flag to indicate if the user wants to see the popup on the map with information about the planning units.
The users profile information.
The name of the default base map that the user has selected.
The current role for the user.
The default report unit to use for reporting areas in various parts of the application.
The runlog.dat provides a log of all of the runs that have been done in the marxan-server instance. In some cases where the server crashed or quit unexpectedly, there may be logs in the run that were not terminated properly. These records can be manually deleted from the log if required.
There are a number of best practices to ensure that the marxan-server is secure and while these changes are not mandatory, they will increase the security to your data.
Secure-Sockets Layer is way of encrypting communication between computer systems and prevents unauthorised access. To enable SSL on marxan-server, set the CERTFILE and KEYFILE values in the server.dat file.
Authentication between marxan-client and marxan-server is done using secure cookie authentication and all secure cookies are encrypted using the COOKIE_RANDOM_VALUE in the server.dat file. See COOKIE_RANDOM_VALUE for more information.
To prevent Cross-Origin Resource Sharing vulnerabilities, by default marxan-server only allows read-write access from those domains that are listed in the PERMITTED_DOMAINS value in the server.dat file. All other domains will only have read-only access. See PERMITTED_DOMAINS for more information.
To disable all security in marxan-server, set the DISABLE_SECURITY constant in the server.dat file to True. All services will now be available without any requirement for authentication. See DISABLE_SECURITY for more information.
By default the admin user has the password 'password' which should be changed before the server is made available to any Marxan Web clients. This can be done using the Change Password window - for more information see User Guide - Change Password window.
To configure you own database to use with marxan-server, set the appropriate settings in the server.dat file. See DATABASE_NAME, DATABASE_HOST, DATABASE_USER, DATABASE_PASSWORD for more information.
marxan-server logs all requests and exceptions to a number of loggers. By default logs are written to the console and to the marxan-server.log file. To disable logging set the DISABLE_FILE_LOGGING setting.
Logs can also be written to Google Cloud Logging and viewed online from the Google Cloud Console Logging screen. To set up Google Cloud Logging:
- Set the value of SERVER_NAME parameter - this is shown in the Google Cloud Logging logs to identify where the log has come from
- Create a service account that has a Log writer role
- Download the service account key onto the Google Cloud Platform Virtual Machine
- Edit the /etc/profile.d/marxan-server.sh file and add the following text replacing PATH with the path to the downloaded *.json key:
export GOOGLE_APPLICATION_CREDENTIALS="<PATH>"
- Restart marxan-server
This section outlines what tasks need to be done periodically or on an ad-hoc basis to ensure Marxan Web runs without problems.
If Marxan Web is not running properly, then there are a number of tools to help you diagnose the problem.
In the Marxan Web client all error messages are reported at the bottom of the screen in a pop up message as shown below.
This is a brief description of the problem - a more complete description and stack trace is available in the browsers console. To open the browsers console:
- In Chrome, goto the Customise and control Google Chrome button in the top right. Click on More tools, Developer Tools and then in the tabs at the bottom of the screen click on the Console tab. The full error message is shown in red.
- In Firefox, goto the Open menu in the top right. Click on Web Developer, Browser Console. The full error message is shown in red.
The Marxan Web client uses caching and service workers to improve performance but when you need to diagnose problems they can often get in the way by caching previous versions of the software. To clear the cache and the servive worker, use Chrome and do the following:
- Open the browser console - see marxan-client console
- Click on the Application tab and in the left pane click on Clear Storage
- Click on the Clear site data button to clear the sites cache
- In the left pane click on Service Workers
- Click on Unregister in the right hand side
If you need to diagnose problems in the marxan-server, you can view the marxan-server log which is shown when you start running marxan-server. For more information see Starting/stopping marxan-server. An example screen shot of the marxan-server log is shown below running on Unix.
This log shows diagnostic information about the marxan-server software including the versions of components and the location of key files. It also shows a full log of all of the requests to the marxan-server from the marxan-client applications. If errors occur in marxan-server these are printed in this log. The type of messages that are logged is controlled by the LOGGING_LEVEL constant in the top of the marxan-server.py file.
To start Marxan Server, run the unix_startup.sh script:
cd marxan-server
sudo unix_startup.sh
On Windows installations it will be started automatically when you click on the Launch Marxan Web shortcut.
The Server can also be started directly using the python file:
cd marxan-server
python marxan-server.py
Starting it directly shows the log directly but should not be used on VMs that disconnect from their clients as this will shut down the python process. In this case it is better to use the unix_startup.sh script.
marxan-server can be stopped using one of the following methods:
- If you are connected to the running instance (i.e. the marxan-server log is visible), then press CTRL+C or CTRL+Fn+Pause or close the window in which it is running
- If the marxan-server log is not visible:
- Connect to the running instance using the following and then stop it as described above.
sudo screen -r
- Use the operating system command to find the process ID of the running Python process, e.g. on Windows use TASKLIST and look for the python.exe process, on Unix use ps -A
- Kill that process using the operating system command, e.g. on Windows use TASKKILL /pid <pid>, on Unix use kill -9 <pid>
If the PostGIS server is stopped for any reason, it can be restarted using the operating system specific commands. For more information search online for starting/stopping the Postgresql/PostGIS server.
To test whether the marxan-server is running properly, goto:
http://<domain>/marxan-server/testTornado
You should see the following if marxan-server is running properly:
If you don't then you can try to clear your site cache and service worker. For more information see Clearing cache and service worker.
To install software updates to marxan-server:
cd marxan-server
unix_update.sh
At the end of the update, the update script will run a set of unit tests to ensure that everything is working properly.
To install software updates to marxan-client:
- In the command prompt, navigate to the marxan-client folder
- Type git pull
- Refresh the Marxan Web page in the browser (you may need to clear your browser cache)
Unit tests can be run for marxan-server in the following way:
cd marxan-server
unittest.sh