{"id":20450050,"url":"https://github.com/ooni/orchestra","last_synced_at":"2025-08-20T17:08:29.388Z","repository":{"id":40295565,"uuid":"83037093","full_name":"ooni/orchestra","owner":"ooni","description":"The OONI Probe Orchestration System","archived":false,"fork":false,"pushed_at":"2022-12-07T01:03:59.000Z","size":3907,"stargazers_count":12,"open_issues_count":28,"forks_count":5,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-08-06T09:38:33.757Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ooni.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-24T11:59:00.000Z","updated_at":"2022-05-19T14:33:52.000Z","dependencies_parsed_at":"2022-08-09T16:38:15.395Z","dependency_job_id":null,"html_url":"https://github.com/ooni/orchestra","commit_stats":null,"previous_names":["thetorproject/proteus"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/ooni/orchestra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Forchestra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Forchestra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Forchestra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Forchestra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ooni","download_url":"https://codeload.github.com/ooni/orchestra/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Forchestra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271353975,"owners_count":24744995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T10:50:05.200Z","updated_at":"2025-08-20T17:08:29.370Z","avatar_url":"https://github.com/ooni.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OONI Orchestra\n\n[![Build Status](https://travis-ci.org/ooni/orchestra.svg)](https://travis-ci.org/ooni/orchestra)\n[![Release](https://img.shields.io/github/release/ooni/orchestra.svg?style=flat-square)](https://github.com/ooni/orchestra/releases)\n\n\nThe OONI Probe Orchestration System.\n\nThis repository contains the various microservices that compose the OONI\nProbe Orchestration System.\n\n## Getting started\n\nWe use a simple `Makefile`. Please, check it out to see how we invoke `go` in\na farily standard way for building and running tests.\n\nTo build all the binaries, run:\n\n```\nmake orchestra\n```\n\nYou should now have inside of `./bin` a series of binaries. The ones you care\nabout are:\n\n```\n./bin/ooni-orchestra\n./bin/ooni-registry\n```\n\nThey both take a config file--you can use\n`orchestrate/ooni-orchestrate.toml.example` (or the `registry` one) as\nexamples, respectively.\n\nTo aid local testing you should set up a local postgres instance with a user\nand a database by running:\n```\nCREATE USER proteus WITH PASSWORD 'changeme';\nCREATE DATABASE proteus;\nGRANT ALL PRIVILEGES ON DATABASE proteus to proteus;\n```\n\nYou should then change the config line in the `database` section for the key\n`url` to something like:\n\n```\n[database]\nurl = \"postgres://proteus:changeme@127.0.0.1:32768/proteus?sslmode=disable\"\n```\n\nFor both `orchestrate/ooni-orchestrate.toml` and\n`registry/ooni-registry.toml`.\n\nYou should then be able to start the services by running:\n\n```\n./bin/ooni-orchestrate --config orchestrate/ooni-orchestrate.toml start\n```\n\n## Components\n\n**registry**\n\nIs responsible for registering probes and keeping tabs on what their related\nmetadata is.\n\n**frontend**\n\nIs the frontend to:\n\n* Setup schedules\n\n* View active schedules\n\n* View active probes\n\n**orchestrate**\n\nIs responsible for receiving events via the admin interface and triggering\nnotifications via `gorush`.\n\nCan also be used to view the event history.\n\n## Building and releasing\n\n- Make sure the `GOPATH` environment variable is set. (For reference, the setup\n  of sbs is `export GOPATH=$HOME` with repositories in `$HOME/src/`; e.g. this\n  repository is `$HOME/src/github.com/ooni/orchestra`).\n\n- Of course, you also need to have golang installed.\n\n- To build for development, run `make orchestra`.\n\n- To create a release, run `make release`.\n\nChecklist before tagging a release:\n\n- Make sure you have updated the changelog\n\n- Make sure you bumped the version number in:\n\n    - `Makefile`\n\n    - `common/orchestra_info.go`\n\n- Make sure all unittests are passing (`make check`)\n\n## Notifications specification\n\nA client needs to register to the proteus-registry service.\n\nThe canonical address for it shall be `https://registry.XXX.YYY.ZZZ/`. We\nalso support the cloudfronted domain as following.\n\n### Registration\n\nUpon first running the app the client needs to registry with the notification\nservice.\n\nOnce a client is registered they can update the various metadata related to the probe by means of an update request (detailed in the following section).\n\nTo register a probe a the following HTTPS request is issued:\n\n**Method**: `POST`\n**Path**: `/api/v1/register`\n**Body**:\n```json\n{\n  \"probe_cc\": \"IT\",\n  \"probe_asn\": \"AS0\",\n  \"platform\": \"android\",\n  \"software_name\": \"ooniprobe-android\",\n  \"software_version\": \"0.1.1\",\n  \"software_language\": \"IT\",\n  \"supported_tests\": [\"tcp_connect\", \"web_connectivity\"],\n  \"network_type\": \"wifi\",\n  \"available_bandwidth\": \"100\",\n  \"token\": \"TOKEN_ID\"\n}\n```\n\nIn particular the `token` field represents the Device Token.\n\nThe registration service will return a `client_id` to be used to update the Device Token as well as other metadata.\n\nThe response looks like this:\n\n```json\n{\"client_id\": \"XXX-YYY-ZZZ-TTT\"}\n```\n\n### Update metadata\n\nIn order do update the metadata you to issue the following request:\n\n**Method**: `PUT`\n**Path**: `/api/v1/update/$CLIENT_ID`\n**Body**:\n```json\n{\n  \"probe_cc\": \"IT\",\n  \"probe_asn\": \"AS0\",\n  \"platform\": \"android\",\n  \"software_name\": \"ooniprobe-android\",\n  \"software_version\": \"0.1.1\",\n  \"supported_tests\": [\"tcp_connect\", \"web_connectivity\"],\n  \"network_type\": \"wifi\",\n  \"available_bandwidth\": \"100\",\n  \"token\": \"NEW_TOKEN_ID\"\n}\n```\n\nThe server will respond with:\n\n```json\n{\"status\": \"ok\"}\n```\n\nin case of an error:\n\n```json\n{\"error\": \"ERROR_MESSAGE\"}\n```\n\n### Notifications\n\nA notification includes in the payload of the silent notification a pingback\nURL that the client needs to connect to in order to receive the task that it\nneed to run to perform the actual measurement.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooni%2Forchestra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fooni%2Forchestra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooni%2Forchestra/lists"}