From 18130c778b509876df5e2ea6db2a70d5bc8179ec Mon Sep 17 00:00:00 2001 From: William Durand Date: Wed, 27 Nov 2024 13:37:03 +0100 Subject: [PATCH] Add docs about Remote Settings --- docs/topics/development/index.md | 1 + docs/topics/development/remote_settings.md | 116 +++++++++++++++++++++ 2 files changed, 117 insertions(+) create mode 100644 docs/topics/development/remote_settings.md diff --git a/docs/topics/development/index.md b/docs/topics/development/index.md index 44053026265b..1696b48f37c2 100644 --- a/docs/topics/development/index.md +++ b/docs/topics/development/index.md @@ -26,5 +26,6 @@ static-files search docs waffle +remote_settings ../../../README.rst ``` diff --git a/docs/topics/development/remote_settings.md b/docs/topics/development/remote_settings.md new file mode 100644 index 000000000000..55fd7fc4e31a --- /dev/null +++ b/docs/topics/development/remote_settings.md @@ -0,0 +1,116 @@ +# Remote Settings + +This page explains how to set up [Remote Settings][] locally, which can be +useful when working on the [Blocklist feature](../blocklist.md). AMO must be +running locally first. Make sure it's available at . + +## Configure addons-server + +Add the following configuration variables to the `local_settings.py` file: + +``` +# When using Docker Desktop - `host.docker.internal` is a special host to allow +# containers to get access to the host system, but that won't work on Linux. +REMOTE_SETTINGS_API_URL = "http://host.docker.internal:8888/v1/" +REMOTE_SETTINGS_WRITER_URL = "http://host.docker.internal:8888/v1/" + +# For Linux, you need to find the IP address of the Remote Settings container: +# REMOTE_SETTINGS_API_URL = "http://172.17.0.1:8888/v1/" +# REMOTE_SETTINGS_WRITER_URL = "http://172.17.0.1:8888/v1/" +``` + +Next, reload everything by running `make up`. + +At this point, AMO should be able to find the Remote Settings local server that +we're going to set up next. + +## Set up Remote Settings + +In order to set up Remote Settings, follow these steps: + +1. Clone +2. Run `make start` +3. Add `127.0.0.1 autograph` to your `/etc/hosts` file + +Verify that Remote Settings is healthy: + +``` +curl http://127.0.0.1:8888/v1/__heartbeat__ +{ + "storage": true, + "permission": true, + "cache": true, + "attachments": true, + "signer": true +} +``` + +## Configure the user/permissions + +First, we need an `admin` account. We can create one with the Remote Settings +API: + +``` +curl -X PUT -H 'Content-Type: application/json' \ + -d '{"data": {"password": "s3cr3t"}}' \ + http://127.0.0.1:8888/v1/accounts/admin +``` + +Next, we need a user for AMO: + +``` +curl -X PUT -H 'Content-Type: application/json' \ + -d '{"data": {"password": "amo_remote_settings_password"}}' \ + http://127.0.0.1:8888/v1/accounts/amo_remote_settings_username +``` + +We then need to give this user _write_ access to the `staging` bucket so that it +can create the `addons-bloomfilters` collection. This is where AMO will write +the new records, which will be propagated to the public bucket/collection +automatically: + +``` +curl -X PUT -H 'Content-Type: application/json' \ + -d '{"permissions": {"write": ["account:amo_remote_settings_username"]}}' \ + -u admin:s3cr3t \ + http://127.0.0.1:8888/v1/buckets/staging +``` + +``` +curl -X PUT -H 'Content-Type: application/json' \ + -u amo_remote_settings_username:amo_remote_settings_password \ + http://127.0.0.1:8888/v1/buckets/staging/collections/addons-bloomfilters +``` + +At this point, AMO should be able to authenticate to Remote Settings. This can +be verified with the following command: + +``` +curl http://olympia.test/services/__heartbeat__ +{ + "cinder": { + "state": true, + "status": "" + }, + "rabbitmq": { + "state": true, + "status": "" + }, + "remotesettings": { + "state": true, + "status": "" + }, + "signer": { + "state": true, + "status": "" + } +} +``` + +After AMO uploads records, the Remote Settings `addons-bloomfilters` collection +will be available at: + + +We are done \o/ + +[Remote Settings]: https://remote-settings.readthedocs.io/en/latest/index.html