A service for checking URLs are safe.

• Git

• pyenv Follow the instructions in the pyenv README to install it. The Homebrew method works best on macOS.

• Docker. Follow the instructions on the Docker website to install Docker.

git clone https://github.com/hypothesis/checkmate.git

This will download the code into a checkmate directory in your current working directory. You need to be in the checkmate directory from the remainder of the installation process:

cd checkmate

Start the services that Checkmate requires using Docker Compose:

make services

Create the database contents and environment variable settings needed to get Checkmate working:

make devdata

make dev

The first time you run make dev it might take a while to start because it'll need to install the application dependencies and build the assets.

This will start the app on http://localhost:9099.

That's it! You’ve finished setting up your Checkmate development environment. Run make help to see all the commands that are available for running the tests, linting, code formatting, etc.

Check a specific URL for problems. The return values are in a JSON:API style.

Return codes:

• 200 - The URL has reasons to block (JSON body)
• 204 - The URL has no reasons to block (no body)
• 400 - There is something wrong with your request

Return examples:

Reasons are listed in decreasing order of severity.

// 200 OK
{
    "data": [
        {
            "type": "reason", "id": "malicious",
            "attributes": {"severity": "mandatory"}
        },
        {
            "type": "reason", "id": "high-io",
            "attributes": {"severity": "advisory"}
        }
    ],
    "meta": {
        "maxSeverity": "mandatory"
    }
}

In the case of errors:

// 400 Bad Request
{
    "errors": [
        {
            "id": "BadURLParameter",
            "detail": "Parameter 'url' is required",
            "source": {"parameter": "url"}
        }
    ]
}

Check the service status

Return codes:

• 200 - If the service is up

Return example:

//200 OK
{"status": "okay"}

Environment variables:

For details of changing the blocklist see:

• https://stackoverflow.com/c/hypothesis/questions/102/250

To authenticate requests to the dev server you must specify an API key via HTTP Basic Authentication. Set the username field to the API key and leave the password blank. In the local development environment a default dev_api_key API key is accepted:

curl http://dev_api_key@localhost:9099/api/check?url=http://example.com/

To access the admin UI for Checkmate, visit http://localhost:9099/ui/admin. You will need to login using an @hypothes.is Google account.