Use the Dev Server

Goals

  • Create remote records
  • Pull them from the server

Prerequisites

This guide assumes you have already installed and set up the following:

  • cURL
  • jq (optional)

Introduction

Remote Settings is built on top of a project called Kinto. As a service to the Kinto community, Mozilla hosts a public instance of Kinto at https://kinto.dev.mozaws.net/v1. Although this server is not officially maintained and has no official connection with the Remote Settings project, it can be convenient to use it when exploring Remote Settings.

Several authentication options are available. We will use local accounts and Basic Auth for the sake of simplicity.

Warning

Since the server is publicly accessible, we flush its content every day. We thus recommend you to keep the initialization commands in a small shell script.

Create your account

Let’s create a user alice with password w0nd3rl4nd.

SERVER=https://kinto.dev.mozaws.net/v1

curl -X PUT ${SERVER}/accounts/alice \
     -d '{"data": {"password": "w0nd3rl4nd"}}' \
     -H 'Content-Type:application/json'

When reaching out the server root URL with these credentials you should see a user entry whose id field is account:alice.

BASIC_AUTH=alice:w0nd3rl4nd

curl -s ${SERVER}/ -u $BASIC_AUTH | jq .user

Create a collection

Choose a name for your settings that makes sense for your use-case and is specific enough (eg. focus-search-engines, not search).

CID=focus-search-engines

Using the REST API, we create a collection:

curl -X PUT ${SERVER}/buckets/main/collections/${CID} \
     -H 'Content-Type:application/json' \
     -u ${BASIC_AUTH}

We create a simple record for testing purposes:

curl -X POST ${SERVER}/buckets/main/collections/${CID}/records \
     -d '{"data": {"title": "example"}}' \
     -H 'Content-Type:application/json' \
     -u ${BASIC_AUTH}

At this point, the server part is ready: it contains a public collection with one record. You can fetch its records with:

curl ${SERVER}/buckets/main/collections/${CID}/records

And it should be listed in the monitor/changes endpoint:

curl ${SERVER}/buckets/monitor/collections/changes/records

Prepare the client

There is no officially “blessed” way to point the client at the dev server. Unlike other environments, the Remote Settings dev tools cannot be used for this purpose. You can change the services.settings.server preference if you like, but because the data in the dev server is not signed, you will get signature verification errors.

Important

This is a critical preference, you should use a dedicated Firefox profile for development.

From your code, or the browser console, register the new collection by listening to the sync event:

const { RemoteSettings } = ChromeUtils.import("resource://services-settings/remote-settings.js", {});

const client = RemoteSettings("focus-search-engines");

// No signature on Dev Server
client.verifySignature = false;

client.on("sync", ({ data }) => {
  // Dump records titles to stdout
  data.current.forEach(r => dump(`${r.title}\n`));
});

Synchronize manually

Then force a synchronization manually with:

await RemoteSettings.pollChanges();

Note

Since the developement server is flushed every day, if the client was previously synchronized with data that is not there anymore, the synchronization might fail. You can start from a new profile (./mach run --temp-profile) or clear the local state manually (using Remote Settings DevTools or development docs about local data).

See also

Check out the dedicated screencast for this operation!

Going further

Now that your client can pull data from the server, you can proceed with more advanced stuff like:

  • Login on the Admin UI and browse your data
  • Create, modify, delete remote records on the server and check out the different sync event data attributes
  • Define a JSON schema on your collection to validate records and have forms in the Admin UI
  • Attach files to your records (see tutorial)
  • If you feel ready, try out the STAGE environment with VPN access, multi signoff (see tutorial), running a local server etc.