Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Aggregate Tomcat Troubleshooting
Read this if:
- You've set up ODK Aggregate and it runs great and you can access it from a browser on your machine.
NOTE: the path after the hostname is case sensitive, so
- 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:
- Refer to Form List shows but Downloads Fail if you can see the list of forms but cannot download them to the phone.
- Refer to Cannot Retrieve List of Forms if you can't even see the list of forms.
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:
- 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.
- 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.
- 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.
- 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,
- 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.
- 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).
humbugmight 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.orgto 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.
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:
- 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
- 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.
- On ODK Aggregate, have you configured it to allow anonymous submissions or configured an ODK username with
Data Collectorprivileges? Refer to Configuring ODK Aggregate Privileges.
- 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
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
- Give the
Data Collectorprivilege to the
anonymousUserby placing a check in the checkbox under the
Save Changesto apply this change.
Configuring an ODK Username
To add a user, give them the
Data Collector privilege, and set a password, do the following:
- Type the username in the text area below the
Add Usersheading. Spaces, commas and semi-colons can be used to delimit multiple usernames.
Addto create this username. The page will refresh with the username(s) appearing in the
- Give the
Data Collectorprivilege to a username by placing a check in the checkbox under the
Save Changes. The table will refresh.
Change Passwordfor the given username. Enter the password in the pop-up dialog and click on the
Change Passwordbutton 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
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
<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.