Skip to content

Aggregate Tomcat Troubleshooting

Jump to bottom Edit New page
Mitch Sundt edited this page Jul 7, 2015 · 1 revision

Introduction

Read this if:

  • You've installed ODK Collect on a phone.
  • You can't get ODK COllect to download forms from ODK Aggregate.

Here are some troubleshooting tips.

Isolating the problem

Verify that your phone isn't in Airport mode... I've forgotten that more times than I can count.

Can you can access the ODK Aggregate home page from your phone's browser?

Can you reach the ODK Aggregate home page from another laptop or computer?

If one or both fail, refer to the Getting Browsers to Work section.

If the browser, works:

Getting Browsers to Work

Here are the two cases for troubleshooting getting the browsers to talk.

Both Phone Browser and Other Browser Fail

Possible causes are:

  1. the name of your webserver is not well-known (browsers typically return a "Server not found error," or a search page, or a set of search results when this happens). Refer to Your Well-Known Server Name. Note that you need to re-run the ODK Aggregate installer and redeploy to Appspot or copy the new war to your Tomcat server directory to update your server name.
  2. you're trying to use HTTPS with a self-signed SSL certificate. ODK Collect will validate the SSL certificate, so if you have a self-signed certificate, the phone will reject the connection until you add the signing certificate to the phone's certificate store (others have posted links on how to do this). If you're trying to do this, first configure and deploy without SSL, get everything working, then configure with SSL.
  3. a firewall running on your webserver is preventing access. On Linux and MacOSX, this is generally the iptables app. You will typically want to open port 80 and, if you have an SSL certificate, port 443. On Windows, this is usually the windows firewall app; refer to Windows Firewall.
  4. there may be a firewall between the devices and the computer (but not on the computer itself) that is preventing access to the computer. This is typically true with larger organizations when the devices are connecting from outside the organization's firewall (e.g., browsers on smartphones). Talk to your network administrator. Firewalls can also be present on cable modems, DSL modems, or WiMax modems. Contact your Internet service provider for assistance.

Only Phone Browser Fails

The phone, especially if it is not using wi-fi hotspots, will be accessing your server from a path through your phone service provider, across the internet, into your organization, and then to your computer. While it may physically be within your office, the path it uses to reach your server will be from across the internet.

If only your phone can't reach the webpage, but another computer can,

  1. the name of your webserver is not well-known on the internet (browsers typically return a "Server not found error," or a search page, or a set of search results when this happens). Refer to Your Well-Known Server Name. Note that you need to re-run the ODK Aggregate installer and redeploy to Appspot or copy the new war to your Tomcat server directory to update your server name.
  2. there may be a firewall between the phone and the computer that is preventing access to the computer. This is typically true with larger organizations. Talk to your network administrator. Firewalls can also be present on cable modems, DSL modems, or WiMax modems. Contact your Internet service provider for assistance.

Your Well-Known Server Name

To troubleshoot the naming of your server:

  • A common configuration problem is specifying "localhost" or "127.0.0.1" for the fully qualified hostname during the ODK Aggregate installation process. This is like saying "myself" -- if you enter that into a browser on the phone or another computer, you're directing that device's browser to connect to the device itself rather than the machine with ODK Aggregate running on it.
  • the hostname you specified may not be fully-qualified, so it might not be a proper name for identifying your computer from outside your organization (from the internet).
For example, humbug might be a name for your server within your organization; from outside, if your organization is grinch.org, then you likely need to specify humbug.grinch.org to identify your computer before devices outside of your organization (e.g., your phone or connections from a wi-fi hotspot in a coffee shop) can find your server. Talk to your network administrator.
  • If you don't have a network administrator, try using Dynamic DNS to give your server a fully-qualified name visible from the internet.

NOTE: you need to re-run the ODK Aggregate installer to update the configuration and resolve this problem.

Windows Firewall

To allow phones and other computers to access ODK Aggregate, you need to open the ports to the server for that access. To do this, open a command window (Start, search for 'cmd'. Right-click, choose 'Run as administrator'.). Within this command window, type:

netsh firewall add portopening TCP 8080 "ODK Aggregate"

This will allow network traffic to access the Tomcat server through port 8080. If you wish to use the standard http port, specify port 80 instead (you must also specify port 80 during the install).

If you wish to use SSL/TLS communication (https:), you must configure Tomcat with an SSL certificate and also open port 443 (repeat the above command, but with 443 replacing 80). The configuration of Tomcat with SSL is well beyond the scope of this document. Refer to the Tomcat website for the steps involved.

After you are done with these steps, you can close the command window.

Cannot Retrieve List of Forms

This assumes you can reach the ODK Aggregate webpage from the phone's browser.

Steps to try:

  1. On ODK Collect, verify that you have specified the full URL to your ODK Aggregate instance. If you have a browser open, the Server URL to specify in ODK Collect is everything before the /Aggregate.html.
  2. On ODK Collect, pay particular attention to whether the host is reached using http or https. ODK Aggregate 1.x is configured to use https whenever possible; this is a change from ODK Aggregate 0.9.x and is easy to overlook when configuring the server URL on the phone.
  3. On ODK Aggregate, have you configured it to allow anonymous submissions or configured an ODK username with Data Collector privileges? Refer to Configuring ODK Aggregate Privileges.
  4. On ODK Collect, have you either left the username/password blank (if allowing anonymous submissions) or specified the ODK username and password for a username with Data Collector privileges?

Note that ODK Collect 1.1.5 and earlier can only connect to an ODK Aggregate instance that allows anonymous submissions. Refer to Configuring ODK Aggregate Privileges.

Configuring ODK Aggregate Privileges

Log onto ODK Aggregate using the super-user Email account, or another account with Site Administrator privileges.

Navigate to the Permissions sub-tab under the Site Admin tab.

Allowing anonymous access

On the Permissions sub-tab:

  1. Give the Data Collector privilege to the anonymousUser by placing a check in the checkbox under the Data Collector heading.
  2. Click Save Changes to apply this change.

Configuring an ODK Username

On the Permissions sub-tab:

To add a user, give them the Data Collector privilege, and set a password, do the following:

  1. Type the username in the text area below the Add Users heading. Spaces, commas and semi-colons can be used to delimit multiple usernames.
  2. Click Add to create this username. The page will refresh with the username(s) appearing in the Edit Users table.
  3. Give the Data Collector privilege to a username by placing a check in the checkbox under the Data Collector heading.
  4. Click Save Changes. The table will refresh.
  5. Click Change Password for the given username. Enter the password in the pop-up dialog and click on the Change Password button on that pop-up.

Form List shows but Downloads Fail

On the phone, from within ODK Collect, you can see the list of forms, but when you choose a form to download, it fails.

This is usually a misconfiguration of ODK Aggregate. You've likely made a change to the hostname in order to access the server, but haven't re-run the ODK Aggregate installer and re-deployed ODK Aggregate in order to make the corresponding update in the server configuration.

To confirm what the problem is, you can open a browser, log onto ODK Aggregate, and then edit the URL and replace /Aggregate.html, and everything after that, with /xformsList

The browser should then show an XML document that is exactly what the phone would have retrieved to display the form list. Pay particular attention to the <downloadUrl> and <manifestUrl> entries in this document. There is likely something wrong with the hostname (or it is specifying http instead of https). You should be able to cut-and-paste the URL of the downloadUrl into a browser and have it download the form definition from the server.

The URLs in this XML document are constructed using the fully-qualified hostname you gave the ODK Aggregate installer. You need to re-run the installer and redeploy your ODK Aggregate instance (either to Appspot or by copying the resulting war file to your Tomcat server) to correct any problems.

NOTES

Add a custom footer
Add a custom sidebar
Clone this wiki locally