https://github.com/ooni/orchestra
The OONI Probe Orchestration System
https://github.com/ooni/orchestra
Last synced: 11 months ago
JSON representation
The OONI Probe Orchestration System
- Host: GitHub
- URL: https://github.com/ooni/orchestra
- Owner: ooni
- License: bsd-3-clause
- Created: 2017-02-24T11:59:00.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-07T01:03:59.000Z (over 3 years ago)
- Last Synced: 2025-08-06T09:38:33.757Z (12 months ago)
- Language: Go
- Homepage:
- Size: 3.73 MB
- Stars: 12
- Watchers: 12
- Forks: 5
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: LICENSE
Awesome Lists containing this project
README
# OONI Orchestra
[](https://travis-ci.org/ooni/orchestra)
[](https://github.com/ooni/orchestra/releases)
The OONI Probe Orchestration System.
This repository contains the various microservices that compose the OONI
Probe Orchestration System.
## Getting started
We use a simple `Makefile`. Please, check it out to see how we invoke `go` in
a farily standard way for building and running tests.
To build all the binaries, run:
```
make orchestra
```
You should now have inside of `./bin` a series of binaries. The ones you care
about are:
```
./bin/ooni-orchestra
./bin/ooni-registry
```
They both take a config file--you can use
`orchestrate/ooni-orchestrate.toml.example` (or the `registry` one) as
examples, respectively.
To aid local testing you should set up a local postgres instance with a user
and a database by running:
```
CREATE USER proteus WITH PASSWORD 'changeme';
CREATE DATABASE proteus;
GRANT ALL PRIVILEGES ON DATABASE proteus to proteus;
```
You should then change the config line in the `database` section for the key
`url` to something like:
```
[database]
url = "postgres://proteus:changeme@127.0.0.1:32768/proteus?sslmode=disable"
```
For both `orchestrate/ooni-orchestrate.toml` and
`registry/ooni-registry.toml`.
You should then be able to start the services by running:
```
./bin/ooni-orchestrate --config orchestrate/ooni-orchestrate.toml start
```
## Components
**registry**
Is responsible for registering probes and keeping tabs on what their related
metadata is.
**frontend**
Is the frontend to:
* Setup schedules
* View active schedules
* View active probes
**orchestrate**
Is responsible for receiving events via the admin interface and triggering
notifications via `gorush`.
Can also be used to view the event history.
## Building and releasing
- Make sure the `GOPATH` environment variable is set. (For reference, the setup
of sbs is `export GOPATH=$HOME` with repositories in `$HOME/src/`; e.g. this
repository is `$HOME/src/github.com/ooni/orchestra`).
- Of course, you also need to have golang installed.
- To build for development, run `make orchestra`.
- To create a release, run `make release`.
Checklist before tagging a release:
- Make sure you have updated the changelog
- Make sure you bumped the version number in:
- `Makefile`
- `common/orchestra_info.go`
- Make sure all unittests are passing (`make check`)
## Notifications specification
A client needs to register to the proteus-registry service.
The canonical address for it shall be `https://registry.XXX.YYY.ZZZ/`. We
also support the cloudfronted domain as following.
### Registration
Upon first running the app the client needs to registry with the notification
service.
Once 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).
To register a probe a the following HTTPS request is issued:
**Method**: `POST`
**Path**: `/api/v1/register`
**Body**:
```json
{
"probe_cc": "IT",
"probe_asn": "AS0",
"platform": "android",
"software_name": "ooniprobe-android",
"software_version": "0.1.1",
"software_language": "IT",
"supported_tests": ["tcp_connect", "web_connectivity"],
"network_type": "wifi",
"available_bandwidth": "100",
"token": "TOKEN_ID"
}
```
In particular the `token` field represents the Device Token.
The registration service will return a `client_id` to be used to update the Device Token as well as other metadata.
The response looks like this:
```json
{"client_id": "XXX-YYY-ZZZ-TTT"}
```
### Update metadata
In order do update the metadata you to issue the following request:
**Method**: `PUT`
**Path**: `/api/v1/update/$CLIENT_ID`
**Body**:
```json
{
"probe_cc": "IT",
"probe_asn": "AS0",
"platform": "android",
"software_name": "ooniprobe-android",
"software_version": "0.1.1",
"supported_tests": ["tcp_connect", "web_connectivity"],
"network_type": "wifi",
"available_bandwidth": "100",
"token": "NEW_TOKEN_ID"
}
```
The server will respond with:
```json
{"status": "ok"}
```
in case of an error:
```json
{"error": "ERROR_MESSAGE"}
```
### Notifications
A notification includes in the payload of the silent notification a pingback
URL that the client needs to connect to in order to receive the task that it
need to run to perform the actual measurement.