Setup a Local Server

Goals

  • Run a local server

  • Pull data from it

  • Setup advanced features like multi signoff and signatures

Prerequisites

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

  • cURL

  • Docker

Introduction

There are several ways to run a local instance of Kinto, the underlying software of Remote Settings.

We will use Docker for the sake of simplicity, but you may find more convenient to install the Python package for example.

Simple Mode (testing)

We will run a local container with the minimal configuration. It should be enough to hack on your Remote Settings integration in the plane. However if your goal is to setup a local server that has the same signoff features as STAGE and PROD, you can continue into the configuration of the next section.

Pull the Docker container:

docker pull mozilla/remote-settings

Create a local folder to receive the potential records attachments, Docker should have the permissions to write it:

mkdir -m 777 attachments  # world writable

Now, we will run the container with the local configuration file and attachments folder mounted:

docker run -v `pwd`/attachments:/tmp/attachments \
           -e KINTO_INI=config/testing.ini \
           -p 8888:8888 \
           mozilla/remote-settings

Your local instance should now be running at http://localhost:8888/v1 and the Admin UI available at http://localhost:8888/v1/admin/

With this configuration, this local server will roughly behave like the DEV server, but without authentication and with a dummy multi-signoff system.

You can now jump to the other tutorial in order to create remote records and synchronize locally.

With Multi-signoff (advanced)

Using a different configuration, we can obtain a local instance that has proper authentication and multi-signoff that interacts with an Autograph instance in order to sign the data, roughly like the STAGE server.

We will run the Autograph container in a separate terminal. Since Autograph generates the x5u certificate chains on startup, we will use a volume mounted on the same location, so that Firefox can download them at the same location as the native x5u URLs (Autograph will point x5u URLs to file:///tmp/attachments).

mkdir -m 777 /tmp/attachments  # world writable
docker run -v /tmp/attachments:/tmp/attachments \
           --rm --name autograph mozilla/autograph

And run the Remote Settings server with a link to autograph container:

docker run --link autograph:autograph \
           -e KINTO_INI=config/local.ini \
           -p 8888:8888 \
           mozilla/remote-settings

Both containers should be connected, and the heartbeat endpoint should only return positive checks:

curl http://localhost:8888/v1/__heartbeat__

{"attachments":true, "cache":true, "permission":true, "signer": true, "storage":true}

Unlike with Simple Mode, we’ll need an admin user:

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

Note

Another option is to clone the mozilla/remote-settings repository and run make start

Prepare the client

The official way to point the client at another server is using the Remote Settings dev tools. This tool can set the constellation of preferences necessary to operate correctly with your local server.

See also

Check out the dedicated screencast for this operation!

What’s next?

  • Create a collection in the main-workspace bucket

  • Assign users to editors and reviewers groups

  • Create records, request review, preview changes in the browser, approve the changes

We cover that in the dedicated multi-signoff tutorial.