Version: 1.0

Quick Start

Get up and running with ODE in approximately 15 minutes.

Overview

This guide walks you through setting up a complete ODE environment and creating your first form.

Step 1: Start Synkronus Server

Using Docker Compose is the fastest method:

# Clone the repository
git clone https://github.com/OpenDataEnsemble/ode.git
cd ode/synkronus

# Start the server with Docker Compose
docker compose up -d

The server will be available at http://localhost:8080.

Step 2: Install Formulus App

Android
iOS

Download and install the APK from the releases page, or build from source:

cd ode/formulus
npm install
npm run android

Build from source (requires macOS and Xcode):

cd ode/formulus
npm install
cd ios && bundle install && bundle exec pod install && cd ..
npm run ios

Step 3: Configure the App

Open the Formulus app
Navigate to Settings
Enter server URL: http://your-server-ip:8080 (or http://localhost:8080 for emulator)
Enter your credentials (create a user account first if needed)
Save the configuration

Step 4: Create Your First Form

Forms are defined using JSON schema. Create a simple form:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "age": {
      "type": "integer",
      "title": "Age",
      "minimum": 0,
      "maximum": 120
    }
  },
  "required": ["name", "age"]
}

Upload this form to your Synkronus server using the API or CLI tool.

Step 5: Collect Data

Open the Formulus app
Navigate to your form
Fill out the form fields
Submit the observation
The data will be stored locally and synchronized to the server

Step 6: Verify Data Collection

Check that your observation was created:

curl
CLI
Portal

curl http://localhost:8080/api/observations \
  -H "Authorization: Bearer YOUR_TOKEN"

synk observations list

Next Steps

Now that you have a working setup:

Learn about form design to create more complex forms
Explore custom applications for specialized workflows
Review the API reference for integration options
Read about synchronization to understand data flow

Troubleshooting

Server Not Accessible

If the mobile app cannot connect to the server:

Physical Device
Android Emulator
iOS Simulator

Verify the server is running: curl http://localhost:8080/health

Check firewall settings

Use your machine's IP address: http://192.168.1.100:8080

Ensure device and server are on the same network

Use 10.0.2.2 instead of localhost: http://10.0.2.2:8080

Verify the server is running on the host machine

Check that port 8080 is accessible

Use localhost or your machine's IP address: http://localhost:8080

Verify the server is running