A service for checking URLs are safe.
-
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:
Name | Effect | Example |
---|---|---|
CHECKMATE_BLOCKLIST_URL |
Where to download the blocklist online | https://some-aws-s3.bucket/file.txt |
CHECKMATE_SECRET |
Secret used for signing URLs | AB823F97FF2E330C1A20 |
PUBLIC_SCHEME |
Scheme used on the public accessible checkmate instance | https |
PUBLIC_HOST |
Host of the public accessible checkmate instance | some-domain.com |
For details of changing the blocklist see:
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.