Need help understanding ODK sync

Hey guys,

I’m having trouble understanding how to get this tutorial working:

And I guess more than that, I’m having trouble understanding what the tutorial even does.

I understand that it spins up an LDAP server, and an LDAP management webapp. Fine, this makes sense to me. I don’t understand what ODK sync UI is and I also don’t understand what ODK sync is either. Does it pull data from ODK into a separate database? Does this docker swarm configuration also spin up an ODK server I can connect to somewhere? Also why are there 2 different tomcat servers running, one for ODK sync and one for ODK sync UI. Can I somehow hit the ODK sync webapp? How is this possible if they’re both running on the same ports and the same localhost url?

Also, in the file [config/web-ui/] there is a property [odk.url] which by default is set to [http://sync:8080/]. Do I need to fill this in with a real value? If so what value should I put into here? I actually tried spinning up a separate ODK server and I put the url to that server in here, but the sync web ui never pulled any forms from the server and when I changed it from default I was no longer able to log in with my LDAP credentials anymore I had to use credentials defined in my ODK server.

My ultimate goal here is to be able to log into ODK via credentials defined in LDAP. Do I misunderstand how these technologies work?


Hi @rrowlands. Are you still using ODK 2’s Sync Endpoints? Just curious from your other thread here: Question about sync-endpoint-default-setup local environment

In any case I’ll respond to this for anyone else who happens upon this thread.

The ODK 2 Sync Endpoints use Docker Swarm to run microservices. There are two different Tomcat servers running the ODK REST API service and the ODK Sync UI service to keep responsibilities separated, to keep each service focused, and to be modular. For example, you can swap in your own Sync UI and not use ours if you like. You could also add your own microservices to the workflow, such as a service to translate data from the ODK database into your own organization’s database and schema.

This default setup also spins up a default database and LDAP. But you should be assessing these with your system administrator if you plan to deploy at scale. These are meant to be a proof of concept and a basic default to get you up and running and able to use the tools.

I do not think you need to update that value. I think it is an internal value that is used inside the docker container. @linl33 can verify or correct me on this.

@Jeff_Beorse is right, the value you see in Sync Web UI’s config (config/web-ui/ is an internal value. In our setup, we call Sync Endpoint’s Docker Service sync. Containers and peers inside the same network as the Sync Endpoint Docker Service can resolve sync to the service’s Docker Swarm load balancer IP address. The DNS resolution is provided by Docker Swarm.

Sync Endpoint and Sync Endpoint Web UI are also not directly exposed to the Internet. They sit behind a NGINX reverse proxy, the proxy then route traffic to the appropriate service base on the path. Optionally, the proxy also handles TLS termination.

@linl33 i’m having some trouble. I keep getting an error 500 due to that internal sync variable not resolving. I built everything from scratch twice today and still not getting it to resolve. What is internally is generating that var? I’m using ODK Sync 2.0 and sources are from the latest git builds. Dockers sitting on a windows machine using Linux containers . Did not see anyone else posting about this issue.


Where are you getting the 500? Is it when visiting the web UI or when visiting the Sync Endpoint API directly? If possible, could you post any relevant error message, logs, etc.

The sync variable is set from the docker-compose.yml file provided by opendatakit/sync-endpoint-default-setup. In that file, Sync Endpoint is started under the name sync.