Setup/configuration issues

[FranckVachon]

Not a issue per se - but rather intended as the beginning of a how-to for setup/configuration.

Assuming installation on some server (AWS, digital ocean, etc) and that the server is up & running, able to receive POST calls from Collect:

How to obtain the vhost-config? Is deploy.sh supposed to generate it (from vhost.js perhaps?)

Are gist/firebase absolutely needed or optional depending on set-up?

Is the repo in the code (simply-odk.org/(gituser)/repo) created manually, or from script (if so which?) or should an alternative be implemented for a new set up as well?

[gmaclennan]

Sorry this is lacking documentation right now.

vhost-config and alias-config are entirely optional. By default you use the URL to define where the blank forms are / where you want to send the submissions.

For example, let's say you want to use the github repo digidem/sample-monitoring-data, then you would configure ODK Collect to use this form server:

http://my-server.com/github/digidem/sample-monitoring-data

Where http://my-server.com is the server where you installed simple-odk. (I recommend using SSL / https if you can)

The vhost-config and aliases are to simplify the URL you use to setup ODK collect. Let's say you have a project "my-project" and you want to use the same repo as above, but not require users to type in that long URL, then you would use this alias-config.json:

{
  "my-project": {
    "formStore": "github",
    "user": "digidem",
    "repo": "sample-monitoring-data",
    "s3bucket": "monitoring-data-bucket"
  }
}

Then the URL for ODK collect would just be:

http://my-server.com/my-project

vhost-config.json is the same, but for having virtual hostnames pointing directly to a particular configuration.

I prefer to not check these files into source control, and use environment variables instead. simple-odk will look for the ALIASES and VHOSTS env variables first, then the files. It expects these env variables to be json strings. Setting env variables to json strings can be a little tricky with shell string escaping. I use deploy.sh to do this for me. dt config:set is a dokku command to set and environment variable in a container.

All of this is only actually useful if you are setting up the server for several different projects. If you only have one project then you can just hardcode the configuration as environment variables as in https://github.com/digidem/my-simple-odk

[gmaclennan]

As for setting up the store on github / gist / firebase, you need to do this manually. All you need to do is put a form XML as a file in the gist or in the /forms forlder in the repo. Basically if looks for any XML files in the gist, or any XML files in the folder /forms in the github repo, assumes they are xForms, and makes an OpenRosa compliant FormList.

Note that FormList is not implemented for Firebase yet - it can only receive submissions.

Any submissions will be saved as:

Github: under the path submissions/FORM_ID/RESPONSE_INSTANCE_ID.geojson Firebase: same as Github Gist: Creates a single .geojson feature collection for each form ID.

Essentially how this all works is that Simple-ODK doesn't really care about where you store the data, it just receives the submissions, figures out where it should go based on the URL and/or environment variables, and saves it as geojson. All authentication is passed through directly to the backend - simple-odk does no auth handling itself.

[FranckVachon]

Ok that makes sense now - I'll try this out on my install & compile this some form next week. Thanks a bunch.

[gmaclennan]

Let me know how it goes. We are working on a front end to set up form stores and upload blank forms. It is still very much at the prototype stage:

Demo / Sourcecode

For viewing / analyzing form responses we are developing MapFilter. Demo. UX discussions.

Any feedback or ideas welcome.