From 9a00fd994400a2526c54eb8c5cd613a15e93ed75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Fri, 23 Sep 2016 21:13:38 +0300 Subject: [PATCH] Mention SITE_NAME in README, better docs for the `unique` API field. --- README.md | 30 ++++++++++++++++++++++----- hc/settings.py | 12 +++++------ static/css/docs.css | 8 +++++++ templates/front/docs_api.html | 39 +++++++++++++++++++++++++++++------ 4 files changed, 72 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index ed95686e..bab54f8b 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,26 @@ The site should now be running at `http://localhost:8080` To log into Django administration site as a super user, visit `http://localhost:8080/admin` +## Configuration + +Site configuration is kept in `hc/settings.py`. Additional configuration +is loaded from `hc/local_settings.py` file, if it exists. You +can create this file (should be right next to `settings.py` in the filesystem) +and override settings as needed. + +Some useful settings keys to override are: + +`SITE_ROOT` is used to build fully qualified URLs for pings, and for use in +emails and notifications. Example: + + SITE_ROOT = "https://my-monitoring-project.com"` + +`SITE_NAME` has the default value of "healthchecks.io" and is used throughout +the templates. Replace it with your own name to personalize your installation. +Example: + + SITE_NAME = "My Monitoring Project" + ## Database Configuration Database configuration is stored in `hc/settings.py` and can be overriden @@ -112,7 +132,6 @@ configuration from environment variables like so: } - ## Sending Emails healthchecks must be able to send email messages, so it can send out login @@ -125,6 +144,7 @@ scenes. For example, the healthchecks.io site uses [django-ses-backend](https://github.com/piotrbulinski/django-ses-backend/) and the email configuration in `hc/local_settings.py` looks as follows: + DEFAULT_FROM_EMAIL = 'noreply@my-monitoring-project.com' DJMAIL_REAL_BACKEND = 'django_ses_backend.SESBackend' AWS_SES_ACCESS_KEY_ID = "put-access-key-here" AWS_SES_SECRET_ACCESS_KEY = "put-secret-access-key-here" @@ -180,11 +200,11 @@ There are separate Django management commands for each task: ``` $ ./manage.py pruneusers - ``` + ``` -When you first try these commands on your data, it is a good idea to -test them on a copy of your database, not on the live database right away. -In a production setup, you should also have regular, automated database +When you first try these commands on your data, it is a good idea to +test them on a copy of your database, not on the live database right away. +In a production setup, you should also have regular, automated database backups set up. ## Integrations diff --git a/hc/settings.py b/hc/settings.py index 025e6c49..ef68610e 100644 --- a/hc/settings.py +++ b/hc/settings.py @@ -84,7 +84,7 @@ TEST_RUNNER = 'hc.api.tests.CustomRunner' DATABASES = { 'default': { 'ENGINE': 'django.db.backends.sqlite3', - 'NAME': './hc.sqlite', + 'NAME': './hc.sqlite', } } @@ -93,9 +93,9 @@ DATABASES = { if os.environ.get("DB") == "postgres": DATABASES = { 'default': { - 'ENGINE': 'django.db.backends.postgresql', - 'NAME': 'hc', - 'USER': 'postgres', + 'ENGINE': 'django.db.backends.postgresql', + 'USER': 'postgres', + 'NAME': 'hc', 'TEST': {'CHARSET': 'UTF8'} } } @@ -104,8 +104,8 @@ if os.environ.get("DB") == "mysql": DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', - 'USER': 'root', - 'NAME': 'hc', + 'USER': 'root', + 'NAME': 'hc', 'TEST': {'CHARSET': 'UTF8'} } } diff --git a/static/css/docs.css b/static/css/docs.css index a0110b22..4455b211 100644 --- a/static/css/docs.css +++ b/static/css/docs.css @@ -50,4 +50,12 @@ a.section { a.section:hover { text-decoration: none; +} + +.page-docs code { + padding: 2px 4px; + font-size: 90%; + color: #427d5e; + background-color: #f2f9f6; + border-radius: 4px; } \ No newline at end of file diff --git a/templates/front/docs_api.html b/templates/front/docs_api.html index bf0ab4d3..21998e56 100644 --- a/templates/front/docs_api.html +++ b/templates/front/docs_api.html @@ -35,7 +35,7 @@ its value should be your API key.

For POST requests, the {% site_name %} API expects request body to be -a JSON document (not a mulitpart/form-data encoded +a JSON document (not a multipart/form-data encoded form data).

@@ -99,6 +99,8 @@ The response may contain a JSON document with additional data.

string, optional, default value: ""

A space-delimited list of tags for the new check.

+

Example:

+ 
{"tags": "reports staging"}
@@ -107,6 +109,8 @@ The response may contain a JSON document with additional data.

number, optional, default value: {{ default_timeout }}.

A number of seconds, the expected period of this check.

Minimum: 60 (one minute), maximum: 604800 (one week).

+

Example for 5 minute timeout:

+ 
{"timeout": 300}
@@ -130,15 +134,38 @@ The response may contain a JSON document with additional data. unique -

array of strings, optional, default value: [].

-

Tells the API to only create a new check if the combination of fields - in unqiue is unique. The fields currently supported are - name, tags, timeout, and grace. If a new check is created the API returns - a 201 code, otherwise it returns a 200 code.

+

array of string values, optional, default value: [].

+

Before creating a check, look for existing checks, filtered + by fields listed in unique. If a matching check is + found, return it with HTTP status code 200. If no matching check is + found, proceed as normal: create a check and return it + with HTTP status code 201.

+ +

The accepted values are: name, + tags, timeout and grace.

+ +

Example:

+ 
{"name": "Backups", unique: ["name"]}
+

In this example, if a check named "Backups" exists, it will + be returned. Otherwise, a new check will be created and + returned.

+

Response Codes

+ + + + + + + + + +
201 CreatedReturned if the check was successfully created.
200 OKReturned if the unique parameter was used and an + existing check was matched.
+

Example Request

{% include "front/snippets/create_check_request.html" %}