Getting Started

We will help you to use Remote Settings in your application!

Create a new official type of Remote Settings

Basically, you will have to go through these 3 steps:

  1. Design your data model (see below) and prepare the list of colleagues that will be allowed to review your data

  2. Request the creation of your collection using this Bugzilla ticket template

  3. While the collection is being created, setup the Mozilla VPN. If you are mentioned as an editor or reviewer, you will be given the appropriate VPN group automatically.

Once done, you will be able to login and edit your records on the Admin UIs:

The records will then be publicly visible at https://firefox.settings.services.mozilla.com/v1/buckets/main/collections/{collection-id}/changeset?_expected=0

Don’t hesitate to contact us (#delivery on Slack) if you’re stuck or have questions about the process!

Check out the screencast to create, request review and approve changes, or our FAQ!

Environments

DEV

STAGE

PROD

Base URL

https://remote-settings-dev.allizom.org/v1/

https://remote-settings.allizom.org/v1/

https://remote-settings.mozilla.org/v1/

Main purpose

Try out API and new use-cases

QA data changes

Deliver data within minutes

Deployed on

pull-request merges

pull-request merges

tagged versions

Access

Public via LDAP Auth

VPN via LDAP groups

VPN via LDAP groups

Permissions

  • Create collections, groups, records

  • Approve own changes

  • CRUD records

  • Approve other’s changes

  • CRUD records

  • Approve other’s changes

Note

In order to switch Firefox from PROD to DEV or STAGE, use the Remote Settings DevTools!

About your data

Name your collection in lowercase with dashes (eg. public-list-suffix, examples).

The Admin UI automatically builds forms based on some metadata for your collection, namely:

  • the list of fields to be displayed as the list columns (eg. title, comment.author)

  • a JSON schema that will be render as a form to create and edit your records (see example)

  • whether you want to control the ID field or let the server assign it automatically

  • whether you want to be able to attach files on records

Note

If your client code expects to find 0 or 1 record by looking up on a specific field, you should probably use that field as the record ID. RemoteSettings("cid").get({filters: {id: "a-value"}}) will be instantaneous.

By default, all records are made available to all users. If you want to control which users should have a particular entry, you can add a filter_expression field (see target filters).

Records vs. Attachments?

Since the diff-based synchronization happens at the record level, it is recommended to keep your Remote Settings records small, especially if you update them often.

It is important to design your data layout carefully, especially if:

  • you have too many records (eg. > 2000)

  • you have big amounts of data (eg. > 1MB)

  • your data cannot be easily broken into pieces

  • your updates are likely to overwrite most of the collection content

Consider the following summary table:

Strategy

Pros

Cons

Many small records

  • Efficient sync

  • Easier to review changes in Admin UI

  • Costly lookups in client

  • Updates potentially harder to automate

Few big records

  • Efficient lookups in client

  • Harder to review changes within records in Admin UI

  • Memory usage in client

Attachments

  • No limit in size & format

  • No partial update

  • Packaging attachments in release binary is feasible but tedious (source)

Base 64 strings in field

  • Easy and simple

  • "ui:widget": "base64file" in Admin schema

  • No extra step to download

  • Limited to a few kilobytes

  • Downloaded by all clients

  • Harder to review changes

Warning

The server will not return more than 10000 objects (records + tombstones) per response. If your collection exceeds this limit, since our clients don’t implement pagination, they won’t be able to synchronize your collection (signature verification will fail).

Attachments Size Limit

Attachments below 20MB will be compressed automatically by the CDN (gzip or brotli).

If you plan on serving bigger attachments:

  • files MUST be compressed upstream, ie. before uploading them on server;

  • an exception MUST be requested by opening a Bugzilla ticket in order to justify this need.

Warning

Serving big files is very (very) costly, especially if they are updated often.

Also, if your client side code requires a specific decompression logic, please reach out to us (#delivery on Slack) to discuss the best way to implement it, we would be happy to generalize what we already have in place internally (eg. zip and .json.mozlz4).

Collection manifests

Both STAGE and PROD collections attributes and permissions are managed via YAML files in the remote-settings-permissions Github repository.

If you want to accelerate the process of getting your collection deployed or adjust its schema, in DEV, STAGE or PROD, you can open a pull-request with the collection, and the definition of {collection}-editors and {collection}-reviewers groups. Check out the existing ones that were merged.

Note

Only members of the mozilla/all-wg workgroup have read access to this repository. If you are part of the mozilla Github organization, you can request your membership via the https://github.com/orgs/mozilla/teams/remote-settings-collections-owners/members team.

Collection Offboarding

If you want to decommission a collection, please open a Bugzilla ticket.

Alternatively, if you have access to the remote-settings-permissions repository, you can fork it and run the following command from its root directory:

./manage.py deletecollection COLLECTION_NAME

And open a pull-request with the command output as description (See this example <https://github.com/mozilla/remote-settings-permissions/pull/748>_).

Note

Deleting a collection is irreversible and will delete all its records and attachments.

The collection won’t be listed in the monitor/changes list, and clients will stop synchronizing it. However, the clients’ local data will remain stored in users’ profiles.