Getting Started with Martus

Last updated: March 20, 2017

Martus Documentation

When you install Martus, all the language versions of the user guide and quick start guide that are currently available are installed in your Martus\Docs directory. If you used the Windows installer, links to these documents are also available by going to Start > Programs > Martus. They are also available at https://martus.org/resources/documentation.html, and you can visit this site to see whether new language versions are available.

System Requirements

Windows

To display your system specifications in Windows, go to Start > Programs > Accessories > System Tools > System Information.

  • Windows XP, Windows Vista, Windows 7, or Windows 8
  • Pentium 233 MHz processor (300 MHz or faster recommended)
  • 512 MB hard disk space available (1 GB or more recommended)
  • Internet connection, to back up data to the Martus server
  • To send records to a Martus Server, your Martus software must not be blocked by a firewall. If you have a software or hardware firewall, it must allow your computer to contact ports 987 or 443, on the Internet. If these ports are blocked when you try to select the server, you will see a message that the server is not responding.
  • Screen resolution of 960x480 or greater

Mac OS

To display your system specifications in Mac, go to the Apple menu > About this Mac > More info… > System report… > Hardware (this is the Hardware Overview).

  • Mac OS 10.7.3 (Lion) or higher
  • Java Runtime Environment (JRE) version 1.8.0_40 or later (sometimes called Java8). The Java community is now supporting JavaFX instead of Swing, and in order to support a multi-lingual Martus, this requires Java8. You can check which version of Java is running on your machine by opening a terminal window and typing “java -version” (without the quotes) and hitting enter/return.
  • 93 MB hard disk space available (100 MB or more recommended)
  • 1GB RAM
  • Internet connection, to back up data to the Martus server
  • To send records to a Martus Server, your Martus software must not be blocked by a firewall. If you have a software or hardware firewall, it must allow your computer to contact ports 987 or 443, on the Internet. If these ports are blocked when you try to select the server, you will see a message that the server is not responding.
  • Screen resolution of 960x480 or greater

Linux

Note: Linux does not fully support versions 5.1, 5.0, and 4.5 of Martus (there are several display issues, etc.). If you want to run Martus 5.1 on Linux, you need Java Runtime Environment (JRE) version 1.8.0_40 (sometimes called Java8) and graphic library gtk2 2.18+ (required for supporting JavaFX). For a fully supported version of Martus, download version 4.4 of Martus and refer to the version 4.3 Martus User Guide.

  • Intel Pentium platform running Linux kernel v. 3.2 or later and glibc v. 2.14 or later
  • Java Runtime Environment (JRE) version 1.8.0_40 (sometimes called Java8). The Java community is now supporting JavaFX instead of Swing, and in order to support a multi-lingual Martus, this requires Java8. You can check which version of Java is running on your machine by opening a terminal window and typing “java -version” (without the quotes) and hitting enter/return.
  • 93 MB hard disk space available (100 MB or more recommended)
  • 256 MB RAM (512 MB or more recommended)
  • Internet connection, to back up data to the Martus server
  • To send records to a Martus Server, your Martus software must not be blocked by a firewall. If you have a software or hardware firewall, it must allow your computer to contact ports 987 or 443, on the Internet. If these ports are blocked when you try to select the server, you will see a message that the server is not responding.
  • At least 16-bit color mode with the KDE or the Gnome desktop recommended

Installing Martus

Download the Martus program and any new language packs from www.martus.org. Martus is continually improving; be sure to check for periodic upgrades available on the Martus website.

Windows

  1. Download Martus from Martus.org or insert a removable memory with the Martus installer. Double click .exe file to launch the installer.
  2. Choose a setup language, and select OK.
  3. intallation step

  4. Select Next and follow the NSIS Install Wizard instructions to install Martus.
  5. intallation step

  6. Decide whether you want to install a Martus shortcut in the Windows Start menu and/or on your desktop. Those that want their use of Martus to be less visible on their compute may want to click no for each of these.

Mac OS

Make sure that Java 8 is installed so that Martus will run properly. You may already have this or an older version of Java, but if you do not, you can download it at the Oracle website.

Automatic installation from a DMG file:

  1. Download the Martus DMG file from the Martus website or CD, and select the file.
  2. If the Martus folder was not automatically opened, double-click on it to view the contents.
  3. An “unknown developer” popup warning may appear, if so, right-click and select Open.
  4. While you can copy the Martus application (Martus.app) to your Applications folder, please note that if you do so, it will not be removed when you uninstall Martus, which may be a security concern. If you do not copy Martus to you Applications folder, you’ll need to open it from the DMG each time.
  5. The Martus Documentation folder contains files with helpful information about Martus, including User Guides, Quick Start Guides, and README files that describe the features in each version, all in various languages. We also suggest that you copy this folder to your computer where you can have easy access to it.

Installation from an ISO file:

Insert the Martus CD into your CD-ROM drive (or download the Martus .iso file from www.martus.org) and double-click it to find the DMG. Follow the DMG instructions above.

Note: If you are using a Martus Language Pack (e.g. Martus-en.mlp), please copy the mlp file to your Martus data folder. For instructions on how to access your Martus data folder, see Why can’t I find my Martus files on my Mac?

Linux

Note: Version 5.1 of Martus does not fully support Linux (there are several display issues, etc.). For a fully supported version of Martus, download version 4.4 of Martus and refer to the version 4.3 Martus User Guide.

The following instructions will install Martus within your user account only. No other Linux users on this machine will have access to Martus. If you want to install Martus publicly, so that any user on this computer can run it, please see Frequently Asked Questions. Most of the following must be done from a terminal command prompt.

  1. See what version of Java you are currently running by typing:

    java -version

    Java must be installed and in your PATH for this to work.

    You must have (or install) either Oracle’s official Java version 1.8.0_40 (sometimes called Java8). If possible, we recommend using the standard software installation tools from your operating system, such as yum/rpm or apt/deb. If you want to run Oracle's JRE but it is not available that way, you can download it directly from http://java.com/

    Note: To run Martus, you only need to install the current version of Java Runtime Environment (JRE), not the larger Java Developer’s Kit (JDK).

  2. Choose and create a directory to hold the Martus program files (i.e. a “Martus program directory”). This may be the same as the Martus data directory (~/.Martus/) or may be different. For example, you might install the Martus application within your Desktop directory, making it easy to find. Separating the program from the data may increase security, but will make it harder to entirely erase Martus if you needed to do so. You would make the directory by typing the following at the prompt in the location you choose:

    mkdir -p < Martus Program Directory>

    For example, if you wanted to install the Martus 4.0 into its data directory, you would type:

    mkdir -p ~/.Martus

  3. If installing from the CD/ISO:
    1. Copy martus.jar from the root directory on the installation CD into the Martus program directory.
    2. Copy the LibExt directory from the CD into Martus program directory, and rename it as ThirdParty.
    3. If desired you can also copy the Documents directory which contains user documentation including the README files that contain a list of changes between versions of Martus.
    4. Change to the directory that contains the actual application, by typing the following:

      cd < Martus Program Directory>

      For example, if you installed Martus into its data directory, you would type:

      cd ~/.Martus

  4. If installing from the zip file:

    Change to the directory you created to install Martus into, extract the zip file contents there, and change to the directory that contains the actual application, by typing the following:

    cd < Martus Program Directory>

    unzip < Path to Zip File>

    cd < Martus Version Directory>

    For example, if you wanted to install the Martus 4.5 into its data directory, and the zip file was in ~/Downloads and named MartusClient- 4.5.zip, you would type:

    cd ~/.Martus

    unzip ~/Downloads/MartusClient- 4.5.zip

  5. Test the installation by running Martus, by typing:

    java -jar `pwd`/martus.jar

    (You do not have to type out the name of the directory you are in, since `pwd` does that for you. )

  6. You can create a shortcut script as follows:

    echo java -jar martus.jar >martus

    chmod +x martus

  7. You can copy this script elsewhere, or you can set up a launcher or shortcut to it, to make it easy to start Martus.

Running Martus in Linux

To start Martus in Linux, run a script you’ve created or type:

java -jar < Martus program directory>/martus.jar

Account Creation

  1. Start Martus
  2. account creation

  3. Select a language from the dropdown in the Martus SignIn dialog box. Select “Want to create a new Martus account?” and the Martus Setup Wizard will walk you through account creation:
  4. account creation

    By clicking the application we arrive at the sign in screen. Here we can choose a language. To open a new account we will click the link. The Wizard walks users through setting up an account in 6 steps:

    1. Create an Account
      • The password is the most important security feature of Martus set by the user. A strong password is long, unique, and something you can remember but others won’t be able to guess. See Creating strong passwords.
      • Enter a unique user name. You can use capital letters, spaces, numbers and symbols. You will need to enter it exactly as it was written each time.
      • Enter Author and Organization information for yourself. These are default values that appear on each record. By entering them here you do not have to write them each time you create a new record. You can always change the default or edit the information that appears on individual records.
    2. Preferences
      • Remember Tor is good to remain anonymous online but could mean slower connections and a red flag to watchers. You should use it only if you have identified it as a need.
      • Choose how you’d like to see the date displayed.
      • Indicate if you need to ensure records are NEVER deleted from the server. This is mainly for those that will share an account or think it is possible an attacker could enter their account. If this doesn’t apply to you, please do not select this option.
    3. Server Preferences
      • The “default” server is in Ireland, with backup/mirror to Brazil. (Reminder that all data is encrypted such that server operators/Benetech/hackers cannot read.)
      • Or you can use another server set-up. For more information on how this works see Administering your own Martus Server
      • Remember that backup can also happen without internet on external drives, if done regularly and off-site, by dragging and dropping .mba files (exported encrypted Martus records) in and out or by backing up your entire Martus directory. (Contacts still must be configured in order to read exported encrypted records). For more details on using Martus with limited internet access and/or low bandwidth see Using Martus without internet/limited access.
    4. Contact Configuration
    5. This step can be skipped and completed from the open account. For detailed instructions see Sharing and Managing your Contacts. To add contacts in the Wizard:

      • The Access Token is like an email address, it needs to be gotten from your contact first and allows you to share with them
      • Locate your own Access Token by clicking on the link at the bottom of the text box on the right.
      • Enter your contact’s Access Token in the field and select the “Add Contact” button
      • The verification window that pops up will help you to ensure you contact is, in fact, the Martus user you would like to be able to share your records with. You will want to verify in person or over the phone that their public code matches the number in the varication window. This way you are sure the contact you are adding is not someone pretending to be your contact or a user with a similar Access Code to your contact that you have mistakenly entered.
      • Name the as you would like them to appear in your address book. This may not be their real name for security reasons and can be a different name than they use in Martus.
    6. Import forms
      • You might want to start with generic forms. A drop down menu will appear to the right
      • You can create your own customized forms with the online Form Builder or Benetech can help you create customized forms. If you already have your form, you can load it in Martus here. You can also do this from the dropdown menus in the main workspace.
    7. Key Backup
      • A Martus account is secured with Username, password and key. The key is a file containing a unique key to your account that unlocks (i.e. deciphers and unencrypts) your data. An encryption key is really difficult and resource-heavy to crack.
      • Benetech cannot recover your account so making sure you can access your data is up to the user.
      • What's the first thing you do when you move into a new home? You make a copy of your key and you put it somewhere safe, not inside your new home.
      • Your key is a .dat file that lives on your computer in your Martus directory and is what lets you into your account; it is associated with your specific username/password pair.
      • You can create a backup key that doesn’t depend on your password from the main Martus workspace.

      Note: Key backup is extremely important. See Backing up your Key for more details.

Your account is now complete. For orientation to the main workspace see Getting to know the Martus Workspace or the Quickstart Guide.

The next time you open Martus, input your username and password in the Martus Sign In dialog box to access your account.

Getting to know the Martus Workspace

workplace

The Main Taskbar

  • Create a record with the click of a button!
  • Toggle your Server connection On and Off:
  • Turn embedded Tor use On and Off:
  • Perform a simple text Search across all of your records.
  • Select Help for information about your Martus version and a link to the Martus documentation.

The Record List Pane

  • Sort your records by multiple fields:
    • On Server (indicates whether or not the record has been saved to your configured server)
    • Author
    • Verified (indicates whether the record was created by a contact that you have verified)
    • Title
    • Date Saved
  • View and Edit records at your convenience.
  • Delete , Export Move and Copy records.

The Sidebar

  • Customize and organize your Cases (which function like folders) with the Label Manager and the Add and Delete options.
  • Manage deleted records in the Trash .
  • Use the Template Manager to upload, download, and edit customized form templates.
  • Upload and download records using the Sync Manager .
  • Import Records into Martus from your local device.

Drop Down Menus

The Martus main page is slow to appear.

I'm running Martus, but I can’t find the Martus window. How can I find it?

Creating Records

  1. Select Create new record .
  2. Input information in the relevant record fields. The record header always contains standard fields:
    1. Title is like the subject of an email, is what will help you distinguish one record from another.
    2. Public Code is a automatically-generated unique code assigned to the Martus account
    3. Select Add Contact to add contacts with whom you want to share the record.
    4. Select Template Selector to choose a different form template for your record.

    records

  3. Standard Martus fields include:
    • Language - Choose the language you’re using to describe the event. If you are using a language that isn’t included in the list, choose Other. You can type your record in any language, regardless of the language selected for the user interface.
    • Author - The Author name from your contact information appears here, but you can change it.
    • Organization – The Organization name from your contact information appears here, but you can change it.
    • Location - Type the location of the event. Depending on the scope of the event, you may enter a country, region, city, or other location. If it doesn’t make sense to enter a location, leave the field blank.
    • Keywords - Type words that are synonyms for acts you described in the record, other related words, and alternative location names, if appropriate. This is especially helpful for searching.
    • Date of Event - Enter the date of the event you’re reporting. Leave the date as Unknown if you are uncertain when the event occurred.
  4. To include Attachments (any file, any size, any number), click Add and then select the file you want to attach. The constraints on attachments are those specific to your device and connection speed – a large attachment may take an unreasonable amount of time to upload on a slow connection.
  5. records

  6. The record details section at the end shows the public code of author, the version number and date created for the record.
  7. Choose to Save, create a new Version, or Share.
  8. Martus automatically saves backup copies of saved, versioned and shared records to the Martus server as long as your configured server is set to ON in the Martus main taskbar.

Manage Attachments

View an Attachment

When creating, editing or viewing a record with an attachment:

  1. Select the Attachments tab within the record window.
  2. Select the View icon, , for the appropriate attachment.

    If the attachment is an image (e.g. photo or scanned document) of certain file types (i.e. jpg, png, gif), the image will be displayed as a thumbnail and in a View Attachment window. Other types of files will be opened outside of Martus by the program you have set on your computer to open that type of file.

    For image attachments with associated geo-location meta-data, select Show on Map to view the location the image was taken on a map.

    map

    Note: Using the Show on Map function will bypass embedded Tor if you have it turned on.

  3. Select Return to image to exit the map.

map2

Save an Attachment

When creating, editing or viewing a record with an attachment:

  1. Select the Attachments tab within the record window.
  2. Select the Save icon, , for the appropriate attachment.
  3. Choose a location to store the attachment and select Save.

map3

Delete an Attachment

  1. Select the Attachments tab within the record window.
  2. Select the Remove icon, , for the appropriate attachment.

Saving, Editing and Versioning Records

Save a Record

Selecting Save once you have created a record allows you modify the original record at a later time without creating a new version of that record. Once you edit and Save a record, you cannot restore the previous version of the record.

  1. Choose Create new record or Edit a record and input data.
  2. Optional: Select Never Delete from Server.
  3. Select Save.

Version a Record

Versioning a record allows you to update information in the record but keep older versions intact, and prevents the earlier versions of the record from being edited. Versions of each record are connected, creating a new copy does not increase the total number of records (e.g., in searches).

  1. Choose Create new record or Edit a record and input data.
  2. Optional: Select Never Delete from Server.
  3. Select Version.

Alternately, you can create a copy of a record to use as a starting point for a new record.

View earlier versions of a record

You can view any version of a record on your computer. However, you can only make changes to a new version.

  1. Select the desired record and choose the Edit icon for that record.
  2. Select the History dropdown form the Create Record window.
  3. Select the record version you would like to view from the list. A separate window will display the past record version.
  4. Select OK to exit to the Create Record window.

Note: If you are allowed to retrieve records from a Contact and you didn’t have access to an earlier version of a Contact’s record, Martus will list the earlier version in the record details, but it won’t retrieve that version of the record to your computer.

Permanently save a record

To ensure that a record is never permanently deleted from the server, even if it is deleted from your local device, Martus offers the option to - individually or as a default - never delete records from your configured backup server.

Permanently Save to the Server by Default

  1. Select Settings > System Preferences.
  2. Check Never Delete from Server.
  3. Select Save Changes.

Permanently Save Individual Records to the Server

  1. Choose Create new record or Edit a record and input data.
  2. Select Never Delete from Server.
  3. Choose to Save, Version, or Share.

Edit a record

  1. Select the record that you would like to edit.
  2. Choose the corresponding Edit icon .
  3. Input/change any record data.
  4. Choose to Save, Version, or Share.

Tip: Consider changing the title of the modified version of the record in a way that makes it clear that it contains corrected or additional information. For example, if the original versioned record is titled “Political leaders jailed,” you might title the modified version “Political leaders jailed – updated.”

Discard changes

To discard the information you’ve entered in a record, click Cancel. Martus alerts you that you’ll be deleting any unsaved information in the record, since it was last saved. Click Yes to discard the unsaved information permanently. (If you click Cancel when you’re modifying a record, the record will revert to the state it was in when you opened it).