mirror of https://github.com/snachodog/mybuddy.git
Break huge README in to multiple files
This commit is contained in:
Christopher C. Wells
Christopher Charbonneau Wells
parent
fab18e6e3a
commit
9a584481f9
683
README.md
683
README.md
|
|
@ -16,27 +16,6 @@ guess work.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
**Table of Contents**
|
|
||||||
|
|
||||||
- [Demo](#demo)
|
|
||||||
- [Deployment](#deployment)
|
|
||||||
- [Docker](#docker)
|
|
||||||
- [Heroku](#heroku)
|
|
||||||
- [Manual](#manual)
|
|
||||||
- [Configuration](#configuration)
|
|
||||||
- [Languages](#languages)
|
|
||||||
- [Import/Export](#importexport)
|
|
||||||
- [Export](#export)
|
|
||||||
- [Import](#import)
|
|
||||||
- [API](#api)
|
|
||||||
- [Authentication](#authentication)
|
|
||||||
- [`GET` Method](#get-method)
|
|
||||||
- [`OPTIONS` Method](#options-method)
|
|
||||||
- [`POST` Method](#post-method)
|
|
||||||
- [`PATCH` Method](#patch-method)
|
|
||||||
- [`DELETE` Method](#delete-method)
|
|
||||||
- [Contributing](#contributing)
|
|
||||||
|
|
||||||
## Demo
|
## Demo
|
||||||
|
|
||||||
A [demo of Baby Buddy](http://demo.baby-buddy.net) is available on Heroku.
|
A [demo of Baby Buddy](http://demo.baby-buddy.net) is available on Heroku.
|
||||||
|
|
@ -45,376 +24,24 @@ The demo instance resets every hour. Login credentials are:
|
||||||
- Username: `admin`
|
- Username: `admin`
|
||||||
- Password: `admin`
|
- Password: `admin`
|
||||||
|
|
||||||
## Deployment
|
## Documentation
|
||||||
|
|
||||||
The default user name and password for Baby Buddy is `admin`/`admin`. For any
|
- [Table of Contents](/docs/TOC.md)
|
||||||
deployment, **log in and change the default admin password immediately**.
|
- [Deployment](/docs/DEPLOYMENT.md)
|
||||||
|
- [Configuration](/docs/CONFIGURATION.md)
|
||||||
Many of Baby Buddy's configuration settings can be controlled using environment
|
- [Import/Export](/docs/IMPORT_EXPORT.md)
|
||||||
variables - see [Configuration](#configuration) for detailed information.
|
- [API](/docs/API.md)
|
||||||
|
- [Contributing](/docs/CONTRIBUTING.md)
|
||||||
### Docker
|
- [Changelog](/CHANGELOG.md)
|
||||||
|
- [Security](/SECURITY.md)
|
||||||
Baby Buddy relies on the [LinuxServer.io](https://www.linuxserver.io/) community
|
- [LICENSE](/LICENSE) (BSD-2 Clause)
|
||||||
for a multi-architecture container with strong support. See
|
|
||||||
[linuxserver/docker-babybuddy](https://github.com/linuxserver/docker-babybuddy)
|
|
||||||
for detailed information about the container or use the following Docker Compose
|
|
||||||
configuration as a template to get started quickly:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
version: "2.1"
|
|
||||||
services:
|
|
||||||
babybuddy:
|
|
||||||
image: ghcr.io/linuxserver/babybuddy
|
|
||||||
container_name: babybuddy
|
|
||||||
environment:
|
|
||||||
- TZ=UTC
|
|
||||||
volumes:
|
|
||||||
- /path/to/appdata:/config
|
|
||||||
ports:
|
|
||||||
- 8000:8000
|
|
||||||
restart: unless-stopped
|
|
||||||
```
|
|
||||||
|
|
||||||
:warning: Baby Buddy v1.7.0 was the final version deployed to
|
|
||||||
[babybuddy/babybuddy](https://hub.docker.com/r/babybuddy/babybuddy) on Docker Hub
|
|
||||||
Future versions of Baby Buddy will use the LSIO container.
|
|
||||||
|
|
||||||
For doing administrative work within the LSIO container, setting an environment variable may be necessary.
|
|
||||||
For example:
|
|
||||||
|
|
||||||
```
|
|
||||||
docker exec -it babybuddy /bin/bash
|
|
||||||
export DJANGO_SETTINGS_MODULE="babybuddy.settings.base"
|
|
||||||
python3 /app/babybuddy/manage.py clearsessions
|
|
||||||
```
|
|
||||||
|
|
||||||
### Heroku
|
|
||||||
|
|
||||||
[](https://heroku.com/deploy)
|
|
||||||
|
|
||||||
For manual deployments to Heroku without using the deploy button, make sure to
|
|
||||||
create the following settings before pushing:
|
|
||||||
|
|
||||||
heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku
|
|
||||||
heroku config:set SECRET_KEY=<CHANGE TO SOMETHING RANDOM>
|
|
||||||
heroku config:set DISABLE_COLLECTSTATIC=1
|
|
||||||
heroku config:set TIME_ZONE=<DESIRED DEFAULT TIMEZONE>
|
|
||||||
|
|
||||||
See [Configuration](#configuration) for other settings that can be controlled
|
|
||||||
by `heroku config:set`.
|
|
||||||
|
|
||||||
And after an initial push, execute the following commands:
|
|
||||||
|
|
||||||
heroku run python manage.py migrate
|
|
||||||
heroku run python manage.py createcachetable
|
|
||||||
|
|
||||||
### Manual
|
|
||||||
|
|
||||||
There are many ways to deploy Baby Buddy manually to any server/VPS. The basic
|
|
||||||
requirements are Python, a web server, an application server, and a database.
|
|
||||||
|
|
||||||
#### Requirements
|
|
||||||
|
|
||||||
- Python 3.6+, pip, pipenv
|
|
||||||
- Web server ([nginx](http://nginx.org/), [Apache](http://httpd.apache.org/), etc.)
|
|
||||||
- Application server ([uwsgi](http://projects.unbit.it/uwsgi), [gunicorn](http://gunicorn.org/), etc.)
|
|
||||||
- Database ([sqlite](https://sqlite.org/), [Postgres](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), etc.)
|
|
||||||
|
|
||||||
#### Example deployment
|
|
||||||
|
|
||||||
*This example assumes a 512MB VPS instance with Ubuntu 18.04.* It uses
|
|
||||||
Python 3.6+, nginx, uwsgi and sqlite and should be sufficient for a few users
|
|
||||||
(e.g. two parents and 1+ child).
|
|
||||||
|
|
||||||
1. Install system packages
|
|
||||||
|
|
||||||
sudo apt-get install python3 python3-pip nginx uwsgi uwsgi-plugin-python3 git libopenjp2-7-dev libpq-dev
|
|
||||||
|
|
||||||
1. Default python3 to python for this session
|
|
||||||
|
|
||||||
alias python=python3
|
|
||||||
|
|
||||||
1. Install pipenv
|
|
||||||
|
|
||||||
sudo -H pip3 install pipenv
|
|
||||||
|
|
||||||
1. Set up directories and files
|
|
||||||
|
|
||||||
sudo mkdir /var/www/babybuddy
|
|
||||||
sudo chown $USER:$(id -gn $USER) /var/www/babybuddy
|
|
||||||
mkdir -p /var/www/babybuddy/data/media
|
|
||||||
git clone https://github.com/babybuddy/babybuddy.git /var/www/babybuddy/public
|
|
||||||
|
|
||||||
1. Move in to the application folder
|
|
||||||
|
|
||||||
cd /var/www/babybuddy/public
|
|
||||||
|
|
||||||
1. Set pipenv to install locally.
|
|
||||||
|
|
||||||
export PIPENV_VENV_IN_PROJECT=1
|
|
||||||
|
|
||||||
1. Initiate and enter the Python environment
|
|
||||||
|
|
||||||
pipenv install --three
|
|
||||||
pipenv shell
|
|
||||||
|
|
||||||
1. Create a production settings file and set the ``SECRET_KEY`` and ``ALLOWED_HOSTS`` values
|
|
||||||
|
|
||||||
cp babybuddy/settings/production.example.py babybuddy/settings/production.py
|
|
||||||
editor babybuddy/settings/production.py
|
|
||||||
|
|
||||||
1. Initiate the application
|
|
||||||
|
|
||||||
export DJANGO_SETTINGS_MODULE=babybuddy.settings.production
|
|
||||||
python manage.py migrate
|
|
||||||
python manage.py createcachetable
|
|
||||||
|
|
||||||
1. Set appropriate permissions on the database and data folder
|
|
||||||
|
|
||||||
sudo chown -R www-data:www-data /var/www/babybuddy/data
|
|
||||||
sudo chmod 640 /var/www/babybuddy/data/db.sqlite3
|
|
||||||
sudo chmod 750 /var/www/babybuddy/data
|
|
||||||
|
|
||||||
1. Create and configure the uwsgi app
|
|
||||||
|
|
||||||
sudo editor /etc/uwsgi/apps-available/babybuddy.ini
|
|
||||||
|
|
||||||
Example config:
|
|
||||||
|
|
||||||
[uwsgi]
|
|
||||||
plugins = python3
|
|
||||||
project = babybuddy
|
|
||||||
base_dir = /var/www/babybuddy
|
|
||||||
|
|
||||||
chdir = %(base_dir)/public
|
|
||||||
virtualenv = %(chdir)/.venv
|
|
||||||
module = %(project).wsgi:application
|
|
||||||
env = DJANGO_SETTINGS_MODULE=%(project).settings.production
|
|
||||||
master = True
|
|
||||||
vacuum = True
|
|
||||||
|
|
||||||
See the [uWSGI documentation](http://uwsgi-docs.readthedocs.io/en/latest/)
|
|
||||||
for more advanced configuration details.
|
|
||||||
|
|
||||||
1. Symlink config and restart uWSGI:
|
|
||||||
|
|
||||||
sudo ln -s /etc/uwsgi/apps-available/babybuddy.ini /etc/uwsgi/apps-enabled/babybuddy.ini
|
|
||||||
sudo service uwsgi restart
|
|
||||||
|
|
||||||
1. Create and configure the nginx server
|
|
||||||
|
|
||||||
sudo editor /etc/nginx/sites-available/babybuddy
|
|
||||||
|
|
||||||
Example config:
|
|
||||||
|
|
||||||
upstream babybuddy {
|
|
||||||
server unix:///var/run/uwsgi/app/babybuddy/socket;
|
|
||||||
}
|
|
||||||
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
server_name babybuddy.example.com;
|
|
||||||
|
|
||||||
location / {
|
|
||||||
uwsgi_pass babybuddy;
|
|
||||||
include uwsgi_params;
|
|
||||||
}
|
|
||||||
|
|
||||||
location /media {
|
|
||||||
alias /var/www/babybuddy/data/media;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
See the [nginx documentation](https://nginx.org/en/docs/) for more advanced
|
|
||||||
configuration details.
|
|
||||||
|
|
||||||
1. Symlink config and restart NGINX:
|
|
||||||
|
|
||||||
sudo ln -s /etc/nginx/sites-available/babybuddy /etc/nginx/sites-enabled/babybuddy
|
|
||||||
sudo service nginx restart
|
|
||||||
|
|
||||||
1. That's it (hopefully)! :tada:
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Environment variables can be used to define a number of configuration settings.
|
|
||||||
Baby Buddy will check the application directory structure for an `.env` file or
|
|
||||||
take these variables from the system environment. **System environment variables
|
|
||||||
take precedence over the contents of an `.env` file.**
|
|
||||||
|
|
||||||
- [`ALLOWED_HOSTS`](#allowed_hosts)
|
|
||||||
- [`ALLOW_UPLOADS`](#allow_uploads)
|
|
||||||
- [`AWS_ACCESS_KEY_ID`](#aws_access_key_id)
|
|
||||||
- [`AWS_SECRET_ACCESS_KEY`](#aws_secret_access_key)
|
|
||||||
- [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
|
|
||||||
- [`DEBUG`](#debug)
|
|
||||||
- [`NAP_START_MAX`](#nap_start_max)
|
|
||||||
- [`NAP_START_MIN`](#nap_start_min)
|
|
||||||
- [`DB_ENGINE`](#db_engine)
|
|
||||||
- [`DB_HOST`](#db_host)
|
|
||||||
- [`DB_NAME`](#db_name)
|
|
||||||
- [`DB_PASSWORD`](#db_password)
|
|
||||||
- [`DB_PORT`](#db_port)
|
|
||||||
- [`DB_USER`](#db_user)
|
|
||||||
- [`SECRET_KEY`](#secret_key)
|
|
||||||
- [`SECURE_PROXY_SSL_HEADER`](#secure_proxy_ssl_header)
|
|
||||||
- [`TIME_ZONE`](#time_zone)
|
|
||||||
- [`USE_24_HOUR_TIME_FORMAT`](#use_24_hour_time_format)
|
|
||||||
|
|
||||||
### `ALLOWED_HOSTS`
|
|
||||||
|
|
||||||
*Default: * (any)*
|
|
||||||
|
|
||||||
This option may be set to a single host or comma-separated list of hosts
|
|
||||||
(without spaces). This should *always* be set to a specific host or hosts in
|
|
||||||
production deployments.
|
|
||||||
|
|
||||||
See also: [Django's documentation on the ALLOWED_HOSTS setting](https://docs.djangoproject.com/en/3.0/ref/settings/#allowed-hosts)
|
|
||||||
|
|
||||||
### `ALLOW_UPLOADS`
|
|
||||||
|
|
||||||
*Default: True*
|
|
||||||
|
|
||||||
Whether or not to allow uploads (e.g. of Child photos). For some deployments
|
|
||||||
(AWS, Heroku) this setting will default to False due to the lack of available
|
|
||||||
persistent storage.
|
|
||||||
|
|
||||||
### `AWS_ACCESS_KEY_ID`
|
|
||||||
|
|
||||||
*Default: None*
|
|
||||||
|
|
||||||
Required to access your AWS S3 bucket, should be uniquely generated per bucket
|
|
||||||
for security.
|
|
||||||
|
|
||||||
See also: [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
|
|
||||||
|
|
||||||
### `AWS_SECRET_ACCESS_KEY`
|
|
||||||
|
|
||||||
*Default: None*
|
|
||||||
|
|
||||||
Required to access your AWS S3 bucket, should be uniquely generated per bucket
|
|
||||||
for security.
|
|
||||||
|
|
||||||
See also: [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
|
|
||||||
|
|
||||||
### `AWS_STORAGE_BUCKET_NAME`
|
|
||||||
|
|
||||||
*Default: None*
|
|
||||||
|
|
||||||
If you would like to use AWS S3 for storage on ephemeral storage platforms like
|
|
||||||
Heroku you will need to create a bucket and add it's name. See django-storages'
|
|
||||||
[Amazon S3 documentation](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html).
|
|
||||||
|
|
||||||
### `DEBUG`
|
|
||||||
|
|
||||||
*Default: False*
|
|
||||||
|
|
||||||
When in debug mode, Baby Buddy will print much more detailed error information
|
|
||||||
for exceptions. This setting should be *False* in production deployments.
|
|
||||||
|
|
||||||
See also [Django's documentation on the DEBUG setting](https://docs.djangoproject.com/en/3.0/ref/settings/#debug).
|
|
||||||
|
|
||||||
### `NAP_START_MAX`
|
|
||||||
|
|
||||||
*Default: 18:00*
|
|
||||||
|
|
||||||
The maximum *start* time (in the instance's time zone) before which a sleep
|
|
||||||
entry is consider a nap. Expects the 24-hour format %H:%M.
|
|
||||||
|
|
||||||
### `NAP_START_MIN`
|
|
||||||
|
|
||||||
*Default: 06:00*
|
|
||||||
|
|
||||||
The minimum *start* time (in the instance's time zone) after which a sleep
|
|
||||||
entry is considered a nap. Expects the 24-hour format %H:%M.
|
|
||||||
|
|
||||||
### `DB_ENGINE`
|
|
||||||
|
|
||||||
*Default: django.db.backends.postgresql*
|
|
||||||
|
|
||||||
The database engine utilized for the deployment.
|
|
||||||
|
|
||||||
See also [Django's documentation on the ENGINE setting](https://docs.djangoproject.com/en/3.0/ref/settings/#engine) .
|
|
||||||
|
|
||||||
### `DB_HOST`
|
|
||||||
|
|
||||||
*Default: db*
|
|
||||||
|
|
||||||
The name of the database host for the deployment.
|
|
||||||
|
|
||||||
### `DB_NAME`
|
|
||||||
|
|
||||||
*Default: postgres*
|
|
||||||
|
|
||||||
The name of the database table utilized for the deployment.
|
|
||||||
|
|
||||||
### `DB_PASSWORD`
|
|
||||||
|
|
||||||
*No Default*
|
|
||||||
|
|
||||||
The password for the database user for the deployment. In the default example, this is the root PostgreSQL password.
|
|
||||||
|
|
||||||
### `DB_PORT`
|
|
||||||
|
|
||||||
*Default: 5432*
|
|
||||||
|
|
||||||
The listening port for the database. The default port is 5432 for PostgreSQL.
|
|
||||||
|
|
||||||
### `DB_USER`
|
|
||||||
|
|
||||||
*Default: postgres*
|
|
||||||
|
|
||||||
The database username utilized for the deployment.
|
|
||||||
|
|
||||||
### `SECRET_KEY`
|
|
||||||
|
|
||||||
*Default: None*
|
|
||||||
|
|
||||||
A random, unique string must be set as the "secret key" before Baby Buddy can
|
|
||||||
be deployed and run.
|
|
||||||
|
|
||||||
See also [Django's documentation on the SECRET_KEY setting](https://docs.djangoproject.com/en/3.0/ref/settings/#secret-key).
|
|
||||||
|
|
||||||
### `SECURE_PROXY_SSL_HEADER`
|
|
||||||
|
|
||||||
*Default: None*
|
|
||||||
|
|
||||||
If Baby Buddy is behind a proxy, you may need to set this to True. This tells Baby Buddy to trust the X-Forwarded-Proto header that comes from your proxy, and any time its value is 'https', then the request is guaranteed to be secure (i.e., it originally came in via HTTPS).
|
|
||||||
|
|
||||||
:warning: Modifying this setting can compromise Baby Buddy’s security. Ensure you fully understand your setup before changing it.
|
|
||||||
|
|
||||||
See also [Django's documentation on the SECURE_PROXY_SSL_HEADER setting](https://docs.djangoproject.com/en/3.0/ref/settings/#secure-proxy-ssl-header).
|
|
||||||
|
|
||||||
### `TIME_ZONE`
|
|
||||||
|
|
||||||
*Default: UTC*
|
|
||||||
|
|
||||||
The default time zone to use for the instance. See [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
|
|
||||||
for all possible values. This value can be overridden per use from the user
|
|
||||||
settings form.
|
|
||||||
|
|
||||||
### `USE_24_HOUR_TIME_FORMAT`
|
|
||||||
|
|
||||||
*Default: False*
|
|
||||||
|
|
||||||
Whether to force 24-hour time format for locales that do not ordinarily use it
|
|
||||||
(e.g. `en`). Support for this feature must implemented on a per-locale basis.
|
|
||||||
See format files under [`babybuddy/formats`](babybuddy/formats) for supported
|
|
||||||
locales.
|
|
||||||
|
|
||||||
Note: This value for this setting is interpreted as a boolean from a string
|
|
||||||
using Python's built-in [`strtobool`](https://docs.python.org/3/distutils/apiref.html#distutils.util.strtobool)
|
|
||||||
tool. Only certain strings are supported (e.g. "True" for `True` and "False" for
|
|
||||||
`False`), other unrecognized strings will cause a `ValueError` and prevent Baby
|
|
||||||
Buddy from loading.
|
|
||||||
|
|
||||||
## Languages
|
## Languages
|
||||||
|
|
||||||
Baby Buddy includes translation support as of v1.2.2. Language can be set on a
|
Baby Buddy is available in a variety of languages thanks to the efforts of numerous
|
||||||
per-user basis from the user settings page (`/user/settings/`). See
|
translators. Language can be set on a per-user basis from the user settings page
|
||||||
[CONTRIBUTING.md](CONTRIBUTING.md#translation) for information about how to
|
(`/user/settings/`). See [CONTRIBUTING.md](/docs/CONTRIBUTING.md#translation)
|
||||||
create/update translations.
|
for information about how to create/update translations.
|
||||||
|
|
||||||
### Available languages
|
### Available languages
|
||||||
|
|
||||||
|
|
@ -442,281 +69,7 @@ create/update translations.
|
||||||
|
|
||||||
:tr: Turkish
|
:tr: Turkish
|
||||||
|
|
||||||
## Import/Export
|
## Reporting Vulnerabilities
|
||||||
|
|
||||||
Baby Buddy uses the [django-import-export application](https://django-import-export.readthedocs.io/)
|
See [SECURITY.md](SECURITY.md) for information about where and how to report
|
||||||
to provide import and export functionality.
|
potential Baby Buddy vulnerabilities.
|
||||||
|
|
||||||
### Export
|
|
||||||
|
|
||||||
Export actions are accessible from Baby Buddy's "Database Admin" area (the
|
|
||||||
Django admin interface). For example, to export all diaper change entries from
|
|
||||||
Baby Buddy as an Excel file:
|
|
||||||
|
|
||||||
1. Log in as a user with "staff" access.
|
|
||||||
|
|
||||||
1. From the user menu, click "Database Admin" under the "Site" heading.
|
|
||||||
|
|
||||||
1. Click "Diaper Changes" in the list of data types.
|
|
||||||
|
|
||||||
1. Click the "Export" button above the filters list on the right side of the
|
|
||||||
screen.
|
|
||||||
|
|
||||||
1. Select the "xlxs" format and click "Submit"
|
|
||||||
|
|
||||||
Note: any applied filters will also filter the exported entries. Alternatively,
|
|
||||||
on the Diaper Change list screen (step 3 above), it is possible to select one
|
|
||||||
or many individual records and select "Export selected Diaper Changes" from the
|
|
||||||
"Actions" list.
|
|
||||||
|
|
||||||
### Import
|
|
||||||
|
|
||||||
Import actions are accessible from Baby Buddy's "Database Admin" area (the
|
|
||||||
Django admin interface). From the list of entry types in the Database Admin,
|
|
||||||
select the type to import and click the "Import" button on the list page. The
|
|
||||||
import screen for a particular type will list the fields generally expected to
|
|
||||||
be present for an import. Multiple file types -- including csv, xlsx, etc. --
|
|
||||||
are supported for the import.
|
|
||||||
|
|
||||||
The import pages do not provide *detailed* information about the required data
|
|
||||||
and formats. When an import is attempted, all rows will be checked for errors
|
|
||||||
and any issues will be reported on screen and will need to be resolved before
|
|
||||||
the import can be performed.
|
|
||||||
|
|
||||||
See the [example import files](core/tests/import) used for tests to get an idea
|
|
||||||
of the expected data format.
|
|
||||||
|
|
||||||
## API
|
|
||||||
|
|
||||||
Baby Buddy uses the [Django REST Framework](https://www.django-rest-framework.org/)
|
|
||||||
(DRF) to provide a REST API.
|
|
||||||
|
|
||||||
The only requirement for (most) requests is that the `Authorization` header is
|
|
||||||
set as described in the [Authentication](#authentication) section. The one
|
|
||||||
exception is the `/api` endpoint, which lists all available endpoints.
|
|
||||||
|
|
||||||
Currently, the following endpoints are available for `GET`, `OPTIONS`, and
|
|
||||||
`POST` requests:
|
|
||||||
|
|
||||||
- `/api/children/`
|
|
||||||
- `/api/changes/` (Diaper Changes)
|
|
||||||
- `/api/feedings/`
|
|
||||||
- `/api/notes/`
|
|
||||||
- `/api/sleep/`
|
|
||||||
- `/api/temperature/`
|
|
||||||
- `/api/timers/`
|
|
||||||
- `/api/tummy-times/`
|
|
||||||
- `/api/weight/`
|
|
||||||
|
|
||||||
### Authentication
|
|
||||||
|
|
||||||
By default, the [TokenAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)
|
|
||||||
and [SessionAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication)
|
|
||||||
classes are enabled. Session authentication covers local API requests made by
|
|
||||||
the application itself. Token authentication allows external requests to be
|
|
||||||
made.
|
|
||||||
|
|
||||||
:exclamation: **In a production environment, token authentication should only
|
|
||||||
be used for API calls to an `https` endpoint.** :exclamation:
|
|
||||||
|
|
||||||
Each user is automatically assigned an API key that can be used for token
|
|
||||||
authentication. This key can be found on the User Settings page for the logged
|
|
||||||
in the user. To use a key for an API request, set the request `Authorization`
|
|
||||||
header to `Token <user-key>`. E.g.
|
|
||||||
|
|
||||||
Authorization: Token 2h23807gd72h7hop382p98hd823dw3g665g56
|
|
||||||
|
|
||||||
If the `Authorization` header is not set or the key is not valid, the API will
|
|
||||||
return `403 Forbidden` with additional details in the response body.
|
|
||||||
|
|
||||||
### Schema
|
|
||||||
|
|
||||||
API schema information in the [OpenAPI format](https://swagger.io/specification/)
|
|
||||||
can be found in the `openapi-schema.yml` file in the project root. A live
|
|
||||||
version is also available at the `/api/schema` path of a running instance.
|
|
||||||
|
|
||||||
### `GET` Method
|
|
||||||
|
|
||||||
#### Request
|
|
||||||
|
|
||||||
The `limit` and `offset` request parameters can be used to limit
|
|
||||||
and offset the results set respectively. For example, the following request
|
|
||||||
will return five diaper changes starting from the 10th diaper change entry:
|
|
||||||
|
|
||||||
curl -X GET 'https://[...]/api/changes/?limit=5&offset=10' -H 'Authorization: Token [...]'
|
|
||||||
{
|
|
||||||
"count": <int>,
|
|
||||||
"next": "https://[...]/api/changes/?limit=5&offset=15",
|
|
||||||
"previous": "https://[...]/api/changes/?limit=5&offset=5",
|
|
||||||
"results": [...]
|
|
||||||
}
|
|
||||||
|
|
||||||
Field-based filters for specific endpoints can be found the in the `filters`
|
|
||||||
field of the `OPTIONS` response for specific endpoints.
|
|
||||||
|
|
||||||
Single entries can also be retrieved by adding the ID (or in the case of a
|
|
||||||
Child entry, the slug) of a particular entry:
|
|
||||||
|
|
||||||
curl -X GET https://[...]/api/children/gregory-hill/ -H 'Authorization: Token [...]'
|
|
||||||
{
|
|
||||||
"id":3,
|
|
||||||
"first_name":"Gregory",
|
|
||||||
"last_name":"Hill",
|
|
||||||
"birth_date":"2020-02-11",
|
|
||||||
"slug":"gregory-hill",
|
|
||||||
"picture":null
|
|
||||||
}
|
|
||||||
curl -X GET https://[...]/api/sleep/1/ -H 'Authorization: Token [...]'
|
|
||||||
{
|
|
||||||
"id":480,
|
|
||||||
"child":3,
|
|
||||||
"start":"2020-03-12T21:25:28.916016-07:00",
|
|
||||||
"end":"2020-03-13T01:34:28.916016-07:00",
|
|
||||||
"duration":"04:09:00",
|
|
||||||
"nap":false
|
|
||||||
}
|
|
||||||
|
|
||||||
#### Response
|
|
||||||
|
|
||||||
Returns JSON data in the response body in the following format:
|
|
||||||
|
|
||||||
{
|
|
||||||
"count":<int>,
|
|
||||||
"next":<url>,
|
|
||||||
"previous":<url>,
|
|
||||||
"results":[{...}]
|
|
||||||
}
|
|
||||||
|
|
||||||
- `count`: Total number of records (*in the database*, not just the response).
|
|
||||||
- `next`: URL for the next set of results.
|
|
||||||
- `previous`: URL for the previous set of results.
|
|
||||||
- `results`: An array of the results of the request.
|
|
||||||
|
|
||||||
For single entries, returns JSON data in the response body keyed by model field
|
|
||||||
names. This will vary between models.
|
|
||||||
|
|
||||||
### `OPTIONS` Method
|
|
||||||
|
|
||||||
#### Request
|
|
||||||
|
|
||||||
All endpoints will respond to an `OPTIONS` request with detailed information
|
|
||||||
about the endpoint's purpose, parameters, filters, etc.
|
|
||||||
|
|
||||||
#### Response
|
|
||||||
|
|
||||||
Returns JSON data in the response body describing the endpoint, available
|
|
||||||
options for `POST` requests, and available filters for `GET` requests. The
|
|
||||||
following example describes the `/api/children` endpoint:
|
|
||||||
|
|
||||||
{
|
|
||||||
"name": "Child List",
|
|
||||||
"renders": [
|
|
||||||
"application/json",
|
|
||||||
"text/html"
|
|
||||||
],
|
|
||||||
"parses": [
|
|
||||||
"application/json",
|
|
||||||
"application/x-www-form-urlencoded",
|
|
||||||
"multipart/form-data"
|
|
||||||
],
|
|
||||||
"actions": {
|
|
||||||
"POST": {
|
|
||||||
"id": {
|
|
||||||
"type": "integer",
|
|
||||||
"required": false,
|
|
||||||
"read_only": true,
|
|
||||||
"label": "ID"
|
|
||||||
},
|
|
||||||
[...]
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"filters": [
|
|
||||||
"first_name",
|
|
||||||
"last_name",
|
|
||||||
"slug"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
|
|
||||||
### `POST` Method
|
|
||||||
|
|
||||||
#### Request
|
|
||||||
|
|
||||||
To add new entries for a particular endpoint, send a `POST` request with the
|
|
||||||
entry data in JSON format in the request body. The `Content-Type` header for
|
|
||||||
`POST` request must be set to `application/json`.
|
|
||||||
|
|
||||||
Regular sanity checks will be performed on relevant data. See the `OPTIONS`
|
|
||||||
response for a particular endpoint for details on required fields and data
|
|
||||||
formats.
|
|
||||||
|
|
||||||
#### Timer Field
|
|
||||||
|
|
||||||
The "timer" field is a special field available for `POST` operations to model
|
|
||||||
endpoints supporting duration (Feeding, Sleep, Tummy Time). When the "timer"
|
|
||||||
field is set in the request, the `start` and `end` fields will be filled in
|
|
||||||
automatically using the `start` and `end` values *from the Timer* (the Timer
|
|
||||||
will be stopped if it is currently running).
|
|
||||||
|
|
||||||
Additionally, if the Timer has a Child relationship, the `child` field will be
|
|
||||||
filled in automatically use the `child` value from the Timer.
|
|
||||||
|
|
||||||
If the "timer" field is set, it's values will **always override** the relevant
|
|
||||||
fields in the request. E.g. if a `POST` request is sent with both the `timer`
|
|
||||||
and `end` fields, the value for the `end` field will be ignored and replaced by
|
|
||||||
the Timer's `end` value. The same applies for `start` and `child`. These fields
|
|
||||||
can all be left out of the request when the Timer is provided, otherwise they
|
|
||||||
are required fields.
|
|
||||||
|
|
||||||
#### Response
|
|
||||||
|
|
||||||
Returns JSON data in the response body describing the added/updated instance or
|
|
||||||
error details if errors exist. Errors are keyed by either the field in error or
|
|
||||||
the general string `non_field_errors` (usually when validation involves
|
|
||||||
multiple fields).
|
|
||||||
|
|
||||||
### `PATCH` Method
|
|
||||||
|
|
||||||
#### Request
|
|
||||||
|
|
||||||
To update existing entries, send a `PATCH` request to the single entry endpoint
|
|
||||||
for the entry to be updated. The `Content-Type` header for `PATCH` request must
|
|
||||||
be set to `application/json`. For example, to update a Diaper Change entry with
|
|
||||||
ID 947 to indicate a "wet" diaper only:
|
|
||||||
|
|
||||||
curl -X PATCH \
|
|
||||||
-H 'Authorization: Token [...]' \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"wet":1, "solid":0}' \
|
|
||||||
https://[...]/api/changes/947/
|
|
||||||
|
|
||||||
Regular sanity checks will be performed on relevant data. See the `OPTIONS`
|
|
||||||
response for a particular endpoint for details on required fields and data
|
|
||||||
formats.
|
|
||||||
|
|
||||||
#### Response
|
|
||||||
|
|
||||||
Returns JSON data in the response body describing the added/updated instance or
|
|
||||||
error details if errors exist. Errors are keyed by either the field in error or
|
|
||||||
the general string `non_field_errors` (usually when validation involves
|
|
||||||
multiple fields).
|
|
||||||
|
|
||||||
### `DELETE` Method
|
|
||||||
|
|
||||||
#### Request
|
|
||||||
|
|
||||||
To delete an existing entry, send a `DELETE` request to the single entry
|
|
||||||
endpoint to be deleted. For example, to delete a Diaper Change entry with ID
|
|
||||||
947:
|
|
||||||
|
|
||||||
curl -X DELETE https://[...]/api/changes/947/ -H 'Authorization: Token [...]'
|
|
||||||
|
|
||||||
#### Response
|
|
||||||
|
|
||||||
Returns an empty response with HTTP status code `204` on success, or a JSON
|
|
||||||
encoded error detail if an error occurred (e.g. `{"detail":"Not found."}` if
|
|
||||||
the requested ID does not exist).
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed
|
|
||||||
information about how to contribute to Baby Buddy.
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,230 @@
|
||||||
|
# API
|
||||||
|
[Back to Table of Contents](/docs/TOC.md)
|
||||||
|
|
||||||
|
Baby Buddy uses the [Django REST Framework](https://www.django-rest-framework.org/)
|
||||||
|
(DRF) to provide a REST API.
|
||||||
|
|
||||||
|
The only requirement for (most) requests is that the `Authorization` header is
|
||||||
|
set as described in the [Authentication](#authentication) section. The one
|
||||||
|
exception is the `/api` endpoint, which lists all available endpoints.
|
||||||
|
|
||||||
|
Currently, the following endpoints are available for `GET`, `OPTIONS`, and
|
||||||
|
`POST` requests:
|
||||||
|
|
||||||
|
- `/api/children/`
|
||||||
|
- `/api/changes/` (Diaper Changes)
|
||||||
|
- `/api/feedings/`
|
||||||
|
- `/api/notes/`
|
||||||
|
- `/api/sleep/`
|
||||||
|
- `/api/temperature/`
|
||||||
|
- `/api/timers/`
|
||||||
|
- `/api/tummy-times/`
|
||||||
|
- `/api/weight/`
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
By default, the [TokenAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)
|
||||||
|
and [SessionAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication)
|
||||||
|
classes are enabled. Session authentication covers local API requests made by
|
||||||
|
the application itself. Token authentication allows external requests to be
|
||||||
|
made.
|
||||||
|
|
||||||
|
:exclamation: **In a production environment, token authentication should only
|
||||||
|
be used for API calls to an `https` endpoint.** :exclamation:
|
||||||
|
|
||||||
|
Each user is automatically assigned an API key that can be used for token
|
||||||
|
authentication. This key can be found on the User Settings page for the logged
|
||||||
|
in the user. To use a key for an API request, set the request `Authorization`
|
||||||
|
header to `Token <user-key>`. E.g.
|
||||||
|
|
||||||
|
Authorization: Token 2h23807gd72h7hop382p98hd823dw3g665g56
|
||||||
|
|
||||||
|
If the `Authorization` header is not set or the key is not valid, the API will
|
||||||
|
return `403 Forbidden` with additional details in the response body.
|
||||||
|
|
||||||
|
## Schema
|
||||||
|
|
||||||
|
API schema information in the [OpenAPI format](https://swagger.io/specification/)
|
||||||
|
can be found in the `openapi-schema.yml` file in the project root. A live
|
||||||
|
version is also available at the `/api/schema` path of a running instance.
|
||||||
|
|
||||||
|
## `GET` Method
|
||||||
|
|
||||||
|
### Request
|
||||||
|
|
||||||
|
The `limit` and `offset` request parameters can be used to limit
|
||||||
|
and offset the results set respectively. For example, the following request
|
||||||
|
will return five diaper changes starting from the 10th diaper change entry:
|
||||||
|
|
||||||
|
curl -X GET 'https://[...]/api/changes/?limit=5&offset=10' -H 'Authorization: Token [...]'
|
||||||
|
{
|
||||||
|
"count": <int>,
|
||||||
|
"next": "https://[...]/api/changes/?limit=5&offset=15",
|
||||||
|
"previous": "https://[...]/api/changes/?limit=5&offset=5",
|
||||||
|
"results": [...]
|
||||||
|
}
|
||||||
|
|
||||||
|
Field-based filters for specific endpoints can be found the in the `filters`
|
||||||
|
field of the `OPTIONS` response for specific endpoints.
|
||||||
|
|
||||||
|
Single entries can also be retrieved by adding the ID (or in the case of a
|
||||||
|
Child entry, the slug) of a particular entry:
|
||||||
|
|
||||||
|
curl -X GET https://[...]/api/children/gregory-hill/ -H 'Authorization: Token [...]'
|
||||||
|
{
|
||||||
|
"id":3,
|
||||||
|
"first_name":"Gregory",
|
||||||
|
"last_name":"Hill",
|
||||||
|
"birth_date":"2020-02-11",
|
||||||
|
"slug":"gregory-hill",
|
||||||
|
"picture":null
|
||||||
|
}
|
||||||
|
curl -X GET https://[...]/api/sleep/1/ -H 'Authorization: Token [...]'
|
||||||
|
{
|
||||||
|
"id":480,
|
||||||
|
"child":3,
|
||||||
|
"start":"2020-03-12T21:25:28.916016-07:00",
|
||||||
|
"end":"2020-03-13T01:34:28.916016-07:00",
|
||||||
|
"duration":"04:09:00",
|
||||||
|
"nap":false
|
||||||
|
}
|
||||||
|
|
||||||
|
### Response
|
||||||
|
|
||||||
|
Returns JSON data in the response body in the following format:
|
||||||
|
|
||||||
|
{
|
||||||
|
"count":<int>,
|
||||||
|
"next":<url>,
|
||||||
|
"previous":<url>,
|
||||||
|
"results":[{...}]
|
||||||
|
}
|
||||||
|
|
||||||
|
- `count`: Total number of records (*in the database*, not just the response).
|
||||||
|
- `next`: URL for the next set of results.
|
||||||
|
- `previous`: URL for the previous set of results.
|
||||||
|
- `results`: An array of the results of the request.
|
||||||
|
|
||||||
|
For single entries, returns JSON data in the response body keyed by model field
|
||||||
|
names. This will vary between models.
|
||||||
|
|
||||||
|
## `OPTIONS` Method
|
||||||
|
|
||||||
|
### Request
|
||||||
|
|
||||||
|
All endpoints will respond to an `OPTIONS` request with detailed information
|
||||||
|
about the endpoint's purpose, parameters, filters, etc.
|
||||||
|
|
||||||
|
### Response
|
||||||
|
|
||||||
|
Returns JSON data in the response body describing the endpoint, available
|
||||||
|
options for `POST` requests, and available filters for `GET` requests. The
|
||||||
|
following example describes the `/api/children` endpoint:
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "Child List",
|
||||||
|
"renders": [
|
||||||
|
"application/json",
|
||||||
|
"text/html"
|
||||||
|
],
|
||||||
|
"parses": [
|
||||||
|
"application/json",
|
||||||
|
"application/x-www-form-urlencoded",
|
||||||
|
"multipart/form-data"
|
||||||
|
],
|
||||||
|
"actions": {
|
||||||
|
"POST": {
|
||||||
|
"id": {
|
||||||
|
"type": "integer",
|
||||||
|
"required": false,
|
||||||
|
"read_only": true,
|
||||||
|
"label": "ID"
|
||||||
|
},
|
||||||
|
[...]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"filters": [
|
||||||
|
"first_name",
|
||||||
|
"last_name",
|
||||||
|
"slug"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
## `POST` Method
|
||||||
|
|
||||||
|
### Request
|
||||||
|
|
||||||
|
To add new entries for a particular endpoint, send a `POST` request with the
|
||||||
|
entry data in JSON format in the request body. The `Content-Type` header for
|
||||||
|
`POST` request must be set to `application/json`.
|
||||||
|
|
||||||
|
Regular sanity checks will be performed on relevant data. See the `OPTIONS`
|
||||||
|
response for a particular endpoint for details on required fields and data
|
||||||
|
formats.
|
||||||
|
|
||||||
|
### Timer Field
|
||||||
|
|
||||||
|
The "timer" field is a special field available for `POST` operations to model
|
||||||
|
endpoints supporting duration (Feeding, Sleep, Tummy Time). When the "timer"
|
||||||
|
field is set in the request, the `start` and `end` fields will be filled in
|
||||||
|
automatically using the `start` and `end` values *from the Timer* (the Timer
|
||||||
|
will be stopped if it is currently running).
|
||||||
|
|
||||||
|
Additionally, if the Timer has a Child relationship, the `child` field will be
|
||||||
|
filled in automatically use the `child` value from the Timer.
|
||||||
|
|
||||||
|
If the "timer" field is set, it's values will **always override** the relevant
|
||||||
|
fields in the request. E.g. if a `POST` request is sent with both the `timer`
|
||||||
|
and `end` fields, the value for the `end` field will be ignored and replaced by
|
||||||
|
the Timer's `end` value. The same applies for `start` and `child`. These fields
|
||||||
|
can all be left out of the request when the Timer is provided, otherwise they
|
||||||
|
are required fields.
|
||||||
|
|
||||||
|
### Response
|
||||||
|
|
||||||
|
Returns JSON data in the response body describing the added/updated instance or
|
||||||
|
error details if errors exist. Errors are keyed by either the field in error or
|
||||||
|
the general string `non_field_errors` (usually when validation involves
|
||||||
|
multiple fields).
|
||||||
|
|
||||||
|
## `PATCH` Method
|
||||||
|
|
||||||
|
### Request
|
||||||
|
|
||||||
|
To update existing entries, send a `PATCH` request to the single entry endpoint
|
||||||
|
for the entry to be updated. The `Content-Type` header for `PATCH` request must
|
||||||
|
be set to `application/json`. For example, to update a Diaper Change entry with
|
||||||
|
ID 947 to indicate a "wet" diaper only:
|
||||||
|
|
||||||
|
curl -X PATCH \
|
||||||
|
-H 'Authorization: Token [...]' \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"wet":1, "solid":0}' \
|
||||||
|
https://[...]/api/changes/947/
|
||||||
|
|
||||||
|
Regular sanity checks will be performed on relevant data. See the `OPTIONS`
|
||||||
|
response for a particular endpoint for details on required fields and data
|
||||||
|
formats.
|
||||||
|
|
||||||
|
### Response
|
||||||
|
|
||||||
|
Returns JSON data in the response body describing the added/updated instance or
|
||||||
|
error details if errors exist. Errors are keyed by either the field in error or
|
||||||
|
the general string `non_field_errors` (usually when validation involves
|
||||||
|
multiple fields).
|
||||||
|
|
||||||
|
## `DELETE` Method
|
||||||
|
|
||||||
|
### Request
|
||||||
|
|
||||||
|
To delete an existing entry, send a `DELETE` request to the single entry
|
||||||
|
endpoint to be deleted. For example, to delete a Diaper Change entry with ID
|
||||||
|
947:
|
||||||
|
|
||||||
|
curl -X DELETE https://[...]/api/changes/947/ -H 'Authorization: Token [...]'
|
||||||
|
|
||||||
|
### Response
|
||||||
|
|
||||||
|
Returns an empty response with HTTP status code `204` on success, or a JSON
|
||||||
|
encoded error detail if an error occurred (e.g. `{"detail":"Not found."}` if
|
||||||
|
the requested ID does not exist).
|
||||||
|
|
@ -0,0 +1,173 @@
|
||||||
|
# Configuration
|
||||||
|
[Back to Table of Contents](/docs/TOC.md)
|
||||||
|
|
||||||
|
Environment variables can be used to define a number of configuration settings.
|
||||||
|
Baby Buddy will check the application directory structure for an `.env` file or
|
||||||
|
take these variables from the system environment. **System environment variables
|
||||||
|
take precedence over the contents of an `.env` file.**
|
||||||
|
|
||||||
|
- [`ALLOWED_HOSTS`](#allowed_hosts)
|
||||||
|
- [`ALLOW_UPLOADS`](#allow_uploads)
|
||||||
|
- [`AWS_ACCESS_KEY_ID`](#aws_access_key_id)
|
||||||
|
- [`AWS_SECRET_ACCESS_KEY`](#aws_secret_access_key)
|
||||||
|
- [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
|
||||||
|
- [`DEBUG`](#debug)
|
||||||
|
- [`NAP_START_MAX`](#nap_start_max)
|
||||||
|
- [`NAP_START_MIN`](#nap_start_min)
|
||||||
|
- [`DB_ENGINE`](#db_engine)
|
||||||
|
- [`DB_HOST`](#db_host)
|
||||||
|
- [`DB_NAME`](#db_name)
|
||||||
|
- [`DB_PASSWORD`](#db_password)
|
||||||
|
- [`DB_PORT`](#db_port)
|
||||||
|
- [`DB_USER`](#db_user)
|
||||||
|
- [`SECRET_KEY`](#secret_key)
|
||||||
|
- [`SECURE_PROXY_SSL_HEADER`](#secure_proxy_ssl_header)
|
||||||
|
- [`TIME_ZONE`](#time_zone)
|
||||||
|
- [`USE_24_HOUR_TIME_FORMAT`](#use_24_hour_time_format)
|
||||||
|
|
||||||
|
## `ALLOWED_HOSTS`
|
||||||
|
|
||||||
|
*Default: * (any)*
|
||||||
|
|
||||||
|
This option may be set to a single host or comma-separated list of hosts
|
||||||
|
(without spaces). This should *always* be set to a specific host or hosts in
|
||||||
|
production deployments.
|
||||||
|
|
||||||
|
See also: [Django's documentation on the ALLOWED_HOSTS setting](https://docs.djangoproject.com/en/3.0/ref/settings/#allowed-hosts)
|
||||||
|
|
||||||
|
## `ALLOW_UPLOADS`
|
||||||
|
|
||||||
|
*Default: True*
|
||||||
|
|
||||||
|
Whether or not to allow uploads (e.g. of Child photos). For some deployments
|
||||||
|
(AWS, Heroku) this setting will default to False due to the lack of available
|
||||||
|
persistent storage.
|
||||||
|
|
||||||
|
## `AWS_ACCESS_KEY_ID`
|
||||||
|
|
||||||
|
*Default: None*
|
||||||
|
|
||||||
|
Required to access your AWS S3 bucket, should be uniquely generated per bucket
|
||||||
|
for security.
|
||||||
|
|
||||||
|
See also: [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
|
||||||
|
|
||||||
|
## `AWS_SECRET_ACCESS_KEY`
|
||||||
|
|
||||||
|
*Default: None*
|
||||||
|
|
||||||
|
Required to access your AWS S3 bucket, should be uniquely generated per bucket
|
||||||
|
for security.
|
||||||
|
|
||||||
|
See also: [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
|
||||||
|
|
||||||
|
## `AWS_STORAGE_BUCKET_NAME`
|
||||||
|
|
||||||
|
*Default: None*
|
||||||
|
|
||||||
|
If you would like to use AWS S3 for storage on ephemeral storage platforms like
|
||||||
|
Heroku you will need to create a bucket and add it's name. See django-storages'
|
||||||
|
[Amazon S3 documentation](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html).
|
||||||
|
|
||||||
|
## `DEBUG`
|
||||||
|
|
||||||
|
*Default: False*
|
||||||
|
|
||||||
|
When in debug mode, Baby Buddy will print much more detailed error information
|
||||||
|
for exceptions. This setting should be *False* in production deployments.
|
||||||
|
|
||||||
|
See also [Django's documentation on the DEBUG setting](https://docs.djangoproject.com/en/3.0/ref/settings/#debug).
|
||||||
|
|
||||||
|
## `NAP_START_MAX`
|
||||||
|
|
||||||
|
*Default: 18:00*
|
||||||
|
|
||||||
|
The maximum *start* time (in the instance's time zone) before which a sleep
|
||||||
|
entry is consider a nap. Expects the 24-hour format %H:%M.
|
||||||
|
|
||||||
|
## `NAP_START_MIN`
|
||||||
|
|
||||||
|
*Default: 06:00*
|
||||||
|
|
||||||
|
The minimum *start* time (in the instance's time zone) after which a sleep
|
||||||
|
entry is considered a nap. Expects the 24-hour format %H:%M.
|
||||||
|
|
||||||
|
## `DB_ENGINE`
|
||||||
|
|
||||||
|
*Default: django.db.backends.postgresql*
|
||||||
|
|
||||||
|
The database engine utilized for the deployment.
|
||||||
|
|
||||||
|
See also [Django's documentation on the ENGINE setting](https://docs.djangoproject.com/en/3.0/ref/settings/#engine) .
|
||||||
|
|
||||||
|
## `DB_HOST`
|
||||||
|
|
||||||
|
*Default: db*
|
||||||
|
|
||||||
|
The name of the database host for the deployment.
|
||||||
|
|
||||||
|
## `DB_NAME`
|
||||||
|
|
||||||
|
*Default: postgres*
|
||||||
|
|
||||||
|
The name of the database table utilized for the deployment.
|
||||||
|
|
||||||
|
## `DB_PASSWORD`
|
||||||
|
|
||||||
|
*No Default*
|
||||||
|
|
||||||
|
The password for the database user for the deployment. In the default example, this is the root PostgreSQL password.
|
||||||
|
|
||||||
|
## `DB_PORT`
|
||||||
|
|
||||||
|
*Default: 5432*
|
||||||
|
|
||||||
|
The listening port for the database. The default port is 5432 for PostgreSQL.
|
||||||
|
|
||||||
|
## `DB_USER`
|
||||||
|
|
||||||
|
*Default: postgres*
|
||||||
|
|
||||||
|
The database username utilized for the deployment.
|
||||||
|
|
||||||
|
## `SECRET_KEY`
|
||||||
|
|
||||||
|
*Default: None*
|
||||||
|
|
||||||
|
A random, unique string must be set as the "secret key" before Baby Buddy can
|
||||||
|
be deployed and run.
|
||||||
|
|
||||||
|
See also [Django's documentation on the SECRET_KEY setting](https://docs.djangoproject.com/en/3.0/ref/settings/#secret-key).
|
||||||
|
|
||||||
|
## `SECURE_PROXY_SSL_HEADER`
|
||||||
|
|
||||||
|
*Default: None*
|
||||||
|
|
||||||
|
If Baby Buddy is behind a proxy, you may need to set this to True. This tells Baby Buddy to trust the X-Forwarded-Proto header that comes from your proxy, and any time its value is 'https', then the request is guaranteed to be secure (i.e., it originally came in via HTTPS).
|
||||||
|
|
||||||
|
:warning: Modifying this setting can compromise Baby Buddy’s security. Ensure you fully understand your setup before changing it.
|
||||||
|
|
||||||
|
See also [Django's documentation on the SECURE_PROXY_SSL_HEADER setting](https://docs.djangoproject.com/en/3.0/ref/settings/#secure-proxy-ssl-header).
|
||||||
|
|
||||||
|
## `TIME_ZONE`
|
||||||
|
|
||||||
|
*Default: UTC*
|
||||||
|
|
||||||
|
The default time zone to use for the instance. See [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
|
||||||
|
for all possible values. This value can be overridden per use from the user
|
||||||
|
settings form.
|
||||||
|
|
||||||
|
## `USE_24_HOUR_TIME_FORMAT`
|
||||||
|
|
||||||
|
*Default: False*
|
||||||
|
|
||||||
|
Whether to force 24-hour time format for locales that do not ordinarily use it
|
||||||
|
(e.g. `en`). Support for this feature must implemented on a per-locale basis.
|
||||||
|
See format files under [`babybuddy/formats`](/babybuddy/formats) for supported
|
||||||
|
locales.
|
||||||
|
|
||||||
|
Note: This value for this setting is interpreted as a boolean from a string
|
||||||
|
using Python's built-in [`strtobool`](https://docs.python.org/3/distutils/apiref.html#distutils.util.strtobool)
|
||||||
|
tool. Only certain strings are supported (e.g. "True" for `True` and "False" for
|
||||||
|
`False`), other unrecognized strings will cause a `ValueError` and prevent Baby
|
||||||
|
Buddy from loading.
|
||||||
|
|
@ -1,21 +1,12 @@
|
||||||
# Contributing
|
# Contributing
|
||||||
|
[Back to Table of Contents](/docs/TOC.md)
|
||||||
- [Contributions](#contributions)
|
|
||||||
- [Pull request process](#pull-request-process)
|
|
||||||
- [Translation](#translation)
|
|
||||||
- [Development](#development)
|
|
||||||
- [Installation](#installation)
|
|
||||||
- [Gulp Commands](#gulp-commands)
|
|
||||||
- [Icon Font](#icon-font)
|
|
||||||
|
|
||||||
## Contributions
|
|
||||||
|
|
||||||
Contributions are accepted and encouraged via GitHub [Issues](https://github.com/babybuddy/babybuddy/issues)
|
Contributions are accepted and encouraged via GitHub [Issues](https://github.com/babybuddy/babybuddy/issues)
|
||||||
and [Pull Requests](https://github.com/babybuddy/babybuddy/pulls). Maintainers
|
and [Pull Requests](https://github.com/babybuddy/babybuddy/pulls). Maintainers
|
||||||
and users may also be found at [babybuddy/Lobby](https://gitter.im/babybuddy/Lobby)
|
and users may also be found at [babybuddy/Lobby](https://gitter.im/babybuddy/Lobby)
|
||||||
on Gitter.
|
on Gitter.
|
||||||
|
|
||||||
### Pull request process
|
## Pull request process
|
||||||
|
|
||||||
1. Fork this repository and commit your changes.
|
1. Fork this repository and commit your changes.
|
||||||
1. Make and commit tests for any new features or major functionality changes.
|
1. Make and commit tests for any new features or major functionality changes.
|
||||||
|
|
@ -29,16 +20,16 @@ on Gitter.
|
||||||
New pull requests will be reviewed by project maintainers as soon as possible
|
New pull requests will be reviewed by project maintainers as soon as possible
|
||||||
and we will do our best to provide feedback and support potential contributors.
|
and we will do our best to provide feedback and support potential contributors.
|
||||||
|
|
||||||
### Translation
|
## Translation
|
||||||
|
|
||||||
#### POEditor
|
### POEditor
|
||||||
|
|
||||||
Baby Buddy is set up as a project on [POEditor](https://poeditor.com/).
|
Baby Buddy is set up as a project on [POEditor](https://poeditor.com/).
|
||||||
Interested contributors can [join translation of Baby Buddy](https://poeditor.com/join/project/QwQqrpTIzn)
|
Interested contributors can [join translation of Baby Buddy](https://poeditor.com/join/project/QwQqrpTIzn)
|
||||||
for access to a simple, web-based frontend for adding/editing translation files
|
for access to a simple, web-based frontend for adding/editing translation files
|
||||||
to the project.
|
to the project.
|
||||||
|
|
||||||
#### Manual
|
### Manual
|
||||||
|
|
||||||
Baby Buddy has support for translation/localization. A manual translation
|
Baby Buddy has support for translation/localization. A manual translation
|
||||||
process will look something like this:
|
process will look something like this:
|
||||||
|
|
@ -98,7 +89,7 @@ documentation section: [Translation](https://docs.djangoproject.com/en/3.0/topic
|
||||||
- NodeJS 14.x and NPM 7.x
|
- NodeJS 14.x and NPM 7.x
|
||||||
- Gulp
|
- Gulp
|
||||||
- Possibly `libpq-dev`
|
- Possibly `libpq-dev`
|
||||||
- This is necessary if `psycopg2` can't find an appropriate prebuild binary.
|
- This is necessary if `psycopg2` can't find an appropriate prebuilt binary.
|
||||||
|
|
||||||
### Installation
|
### Installation
|
||||||
|
|
||||||
|
|
@ -203,7 +194,7 @@ for more details about other options and functionality of this command.
|
||||||
|
|
||||||
#### `coverage`
|
#### `coverage`
|
||||||
|
|
||||||
Create a test coverage report. See [`.coveragerc`](.coveragerc) for default
|
Create a test coverage report. See [`.coveragerc`](/.coveragerc) for default
|
||||||
settings information.
|
settings information.
|
||||||
|
|
||||||
#### `createcachetable`
|
#### `createcachetable`
|
||||||
|
|
@ -281,7 +272,7 @@ used for individual test execution.
|
||||||
#### `updateglyphs`
|
#### `updateglyphs`
|
||||||
|
|
||||||
Downloads generated glyph font files data from [Fonttello](https://fontello.com/)
|
Downloads generated glyph font files data from [Fonttello](https://fontello.com/)
|
||||||
based on [`config.json` file](babybuddy/static_src/fontello/config.json). This
|
based on [`config.json` file](/babybuddy/static_src/fontello/config.json). This
|
||||||
only needs to be run after making changes to the config file.
|
only needs to be run after making changes to the config file.
|
||||||
|
|
||||||
#### `updatestatic`
|
#### `updatestatic`
|
||||||
|
|
@ -300,6 +291,6 @@ are made to Baby Buddy's frontend code (SASS, JS, etc.).
|
||||||
### Icon Font
|
### Icon Font
|
||||||
|
|
||||||
Baby Buddy uses [Fontello](https://fontello.com/) to build a custom icon font
|
Baby Buddy uses [Fontello](https://fontello.com/) to build a custom icon font
|
||||||
for icons used throughout the application. See [`babybuddy/static_src/fontello`](babybuddy/static_src/fontello)
|
for icons used throughout the application. See [`babybuddy/static_src/fontello`](/babybuddy/static_src/fontello)
|
||||||
for further documentation about using the config file with Fontello and license
|
for further documentation about using the config file with Fontello and license
|
||||||
information for fonts used by this application.
|
information for fonts used by this application.
|
||||||
|
|
@ -0,0 +1,191 @@
|
||||||
|
# Deployment
|
||||||
|
[Back to Table of Contents](/docs/TOC.md)
|
||||||
|
|
||||||
|
The default user name and password for Baby Buddy is `admin`/`admin`. For any
|
||||||
|
deployment, **log in and change the default admin password immediately**.
|
||||||
|
|
||||||
|
Many of Baby Buddy's configuration settings can be controlled using environment
|
||||||
|
variables - see [Configuration](/docs/CONFIGURATION.md) for detailed information.
|
||||||
|
|
||||||
|
## Docker
|
||||||
|
|
||||||
|
Baby Buddy relies on the [LinuxServer.io](https://www.linuxserver.io/) community
|
||||||
|
for a multi-architecture container with strong support. See
|
||||||
|
[linuxserver/docker-babybuddy](https://github.com/linuxserver/docker-babybuddy)
|
||||||
|
for detailed information about the container or use the following Docker Compose
|
||||||
|
configuration as a template to get started quickly:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "2.1"
|
||||||
|
services:
|
||||||
|
babybuddy:
|
||||||
|
image: ghcr.io/linuxserver/babybuddy
|
||||||
|
container_name: babybuddy
|
||||||
|
environment:
|
||||||
|
- TZ=UTC
|
||||||
|
volumes:
|
||||||
|
- /path/to/appdata:/config
|
||||||
|
ports:
|
||||||
|
- 8000:8000
|
||||||
|
restart: unless-stopped
|
||||||
|
```
|
||||||
|
|
||||||
|
:warning: Baby Buddy v1.7.0 was the final version deployed to
|
||||||
|
[babybuddy/babybuddy](https://hub.docker.com/r/babybuddy/babybuddy) on Docker Hub
|
||||||
|
Future versions of Baby Buddy will use the LSIO container.
|
||||||
|
|
||||||
|
For doing administrative work within the LSIO container, setting an environment variable may be necessary.
|
||||||
|
For example:
|
||||||
|
|
||||||
|
```
|
||||||
|
docker exec -it babybuddy /bin/bash
|
||||||
|
export DJANGO_SETTINGS_MODULE="babybuddy.settings.base"
|
||||||
|
python3 /app/babybuddy/manage.py clearsessions
|
||||||
|
```
|
||||||
|
|
||||||
|
## Heroku
|
||||||
|
|
||||||
|
[](https://heroku.com/deploy)
|
||||||
|
|
||||||
|
For manual deployments to Heroku without using the deploy button, make sure to
|
||||||
|
create the following settings before pushing:
|
||||||
|
|
||||||
|
heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku
|
||||||
|
heroku config:set SECRET_KEY=<CHANGE TO SOMETHING RANDOM>
|
||||||
|
heroku config:set DISABLE_COLLECTSTATIC=1
|
||||||
|
heroku config:set TIME_ZONE=<DESIRED DEFAULT TIMEZONE>
|
||||||
|
|
||||||
|
See [Configuration](/docs/CONFIGURATION.md) for other settings that can be controlled
|
||||||
|
by `heroku config:set`.
|
||||||
|
|
||||||
|
And after an initial push, execute the following commands:
|
||||||
|
|
||||||
|
heroku run python manage.py migrate
|
||||||
|
heroku run python manage.py createcachetable
|
||||||
|
|
||||||
|
## Manual
|
||||||
|
|
||||||
|
There are many ways to deploy Baby Buddy manually to any server/VPS. The basic
|
||||||
|
requirements are Python, a web server, an application server, and a database.
|
||||||
|
|
||||||
|
### Requirements
|
||||||
|
|
||||||
|
- Python 3.6+, pip, pipenv
|
||||||
|
- Web server ([nginx](http://nginx.org/), [Apache](http://httpd.apache.org/), etc.)
|
||||||
|
- Application server ([uwsgi](http://projects.unbit.it/uwsgi), [gunicorn](http://gunicorn.org/), etc.)
|
||||||
|
- Database ([sqlite](https://sqlite.org/), [Postgres](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), etc.)
|
||||||
|
|
||||||
|
### Example deployment
|
||||||
|
|
||||||
|
*This example assumes a 512MB VPS instance with Ubuntu 18.04.* It uses
|
||||||
|
Python 3.6+, nginx, uwsgi and sqlite and should be sufficient for a few users
|
||||||
|
(e.g. two parents and 1+ child).
|
||||||
|
|
||||||
|
1. Install system packages
|
||||||
|
|
||||||
|
sudo apt-get install python3 python3-pip nginx uwsgi uwsgi-plugin-python3 git libopenjp2-7-dev libpq-dev
|
||||||
|
|
||||||
|
1. Default python3 to python for this session
|
||||||
|
|
||||||
|
alias python=python3
|
||||||
|
|
||||||
|
1. Install pipenv
|
||||||
|
|
||||||
|
sudo -H pip3 install pipenv
|
||||||
|
|
||||||
|
1. Set up directories and files
|
||||||
|
|
||||||
|
sudo mkdir /var/www/babybuddy
|
||||||
|
sudo chown $USER:$(id -gn $USER) /var/www/babybuddy
|
||||||
|
mkdir -p /var/www/babybuddy/data/media
|
||||||
|
git clone https://github.com/babybuddy/babybuddy.git /var/www/babybuddy/public
|
||||||
|
|
||||||
|
1. Move in to the application folder
|
||||||
|
|
||||||
|
cd /var/www/babybuddy/public
|
||||||
|
|
||||||
|
1. Set pipenv to install locally.
|
||||||
|
|
||||||
|
export PIPENV_VENV_IN_PROJECT=1
|
||||||
|
|
||||||
|
1. Initiate and enter the Python environment
|
||||||
|
|
||||||
|
pipenv install --three
|
||||||
|
pipenv shell
|
||||||
|
|
||||||
|
1. Create a production settings file and set the ``SECRET_KEY`` and ``ALLOWED_HOSTS`` values
|
||||||
|
|
||||||
|
cp babybuddy/settings/production.example.py babybuddy/settings/production.py
|
||||||
|
editor babybuddy/settings/production.py
|
||||||
|
|
||||||
|
1. Initiate the application
|
||||||
|
|
||||||
|
export DJANGO_SETTINGS_MODULE=babybuddy.settings.production
|
||||||
|
python manage.py migrate
|
||||||
|
python manage.py createcachetable
|
||||||
|
|
||||||
|
1. Set appropriate permissions on the database and data folder
|
||||||
|
|
||||||
|
sudo chown -R www-data:www-data /var/www/babybuddy/data
|
||||||
|
sudo chmod 640 /var/www/babybuddy/data/db.sqlite3
|
||||||
|
sudo chmod 750 /var/www/babybuddy/data
|
||||||
|
|
||||||
|
1. Create and configure the uwsgi app
|
||||||
|
|
||||||
|
sudo editor /etc/uwsgi/apps-available/babybuddy.ini
|
||||||
|
|
||||||
|
Example config:
|
||||||
|
|
||||||
|
[uwsgi]
|
||||||
|
plugins = python3
|
||||||
|
project = babybuddy
|
||||||
|
base_dir = /var/www/babybuddy
|
||||||
|
|
||||||
|
chdir = %(base_dir)/public
|
||||||
|
virtualenv = %(chdir)/.venv
|
||||||
|
module = %(project).wsgi:application
|
||||||
|
env = DJANGO_SETTINGS_MODULE=%(project).settings.production
|
||||||
|
master = True
|
||||||
|
vacuum = True
|
||||||
|
|
||||||
|
See the [uWSGI documentation](http://uwsgi-docs.readthedocs.io/en/latest/)
|
||||||
|
for more advanced configuration details.
|
||||||
|
|
||||||
|
1. Symlink config and restart uWSGI:
|
||||||
|
|
||||||
|
sudo ln -s /etc/uwsgi/apps-available/babybuddy.ini /etc/uwsgi/apps-enabled/babybuddy.ini
|
||||||
|
sudo service uwsgi restart
|
||||||
|
|
||||||
|
1. Create and configure the nginx server
|
||||||
|
|
||||||
|
sudo editor /etc/nginx/sites-available/babybuddy
|
||||||
|
|
||||||
|
Example config:
|
||||||
|
|
||||||
|
upstream babybuddy {
|
||||||
|
server unix:///var/run/uwsgi/app/babybuddy/socket;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name babybuddy.example.com;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
uwsgi_pass babybuddy;
|
||||||
|
include uwsgi_params;
|
||||||
|
}
|
||||||
|
|
||||||
|
location /media {
|
||||||
|
alias /var/www/babybuddy/data/media;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
See the [nginx documentation](https://nginx.org/en/docs/) for more advanced
|
||||||
|
configuration details.
|
||||||
|
|
||||||
|
1. Symlink config and restart NGINX:
|
||||||
|
|
||||||
|
sudo ln -s /etc/nginx/sites-available/babybuddy /etc/nginx/sites-enabled/babybuddy
|
||||||
|
sudo service nginx restart
|
||||||
|
|
||||||
|
1. That's it (hopefully)! :tada:
|
||||||
|
|
@ -0,0 +1,44 @@
|
||||||
|
## Import/Export
|
||||||
|
[Back to Table of Contents](/docs/TOC.md)
|
||||||
|
|
||||||
|
Baby Buddy uses the [django-import-export application](https://django-import-export.readthedocs.io/)
|
||||||
|
to provide import and export functionality.
|
||||||
|
|
||||||
|
### Export
|
||||||
|
|
||||||
|
Export actions are accessible from Baby Buddy's "Database Admin" area (the
|
||||||
|
Django admin interface). For example, to export all diaper change entries from
|
||||||
|
Baby Buddy as an Excel file:
|
||||||
|
|
||||||
|
1. Log in as a user with "staff" access.
|
||||||
|
|
||||||
|
1. From the user menu, click "Database Admin" under the "Site" heading.
|
||||||
|
|
||||||
|
1. Click "Diaper Changes" in the list of data types.
|
||||||
|
|
||||||
|
1. Click the "Export" button above the filters list on the right side of the
|
||||||
|
screen.
|
||||||
|
|
||||||
|
1. Select the "xlxs" format and click "Submit"
|
||||||
|
|
||||||
|
Note: any applied filters will also filter the exported entries. Alternatively,
|
||||||
|
on the Diaper Change list screen (step 3 above), it is possible to select one
|
||||||
|
or many individual records and select "Export selected Diaper Changes" from the
|
||||||
|
"Actions" list.
|
||||||
|
|
||||||
|
### Import
|
||||||
|
|
||||||
|
Import actions are accessible from Baby Buddy's "Database Admin" area (the
|
||||||
|
Django admin interface). From the list of entry types in the Database Admin,
|
||||||
|
select the type to import and click the "Import" button on the list page. The
|
||||||
|
import screen for a particular type will list the fields generally expected to
|
||||||
|
be present for an import. Multiple file types -- including csv, xlsx, etc. --
|
||||||
|
are supported for the import.
|
||||||
|
|
||||||
|
The import pages do not provide *detailed* information about the required data
|
||||||
|
and formats. When an import is attempted, all rows will be checked for errors
|
||||||
|
and any issues will be reported on screen and will need to be resolved before
|
||||||
|
the import can be performed.
|
||||||
|
|
||||||
|
See the [example import files](/core/tests/import) used for tests to get an idea
|
||||||
|
of the expected data format.
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
# Baby Buddy Documentation
|
||||||
|
|
||||||
|
- [README](/README.md)
|
||||||
|
|
||||||
|
General information about Baby Buddy.
|
||||||
|
|
||||||
|
|
||||||
|
- [Deployment](/docs/DEPLOYMENT.md)
|
||||||
|
|
||||||
|
How to deploy Baby Buddy manually or using Docker or Heroku.
|
||||||
|
|
||||||
|
|
||||||
|
- [Configuration](/docs/CONFIGURATION.md)
|
||||||
|
|
||||||
|
How to set application-wide configuration options using environment variables.
|
||||||
|
|
||||||
|
|
||||||
|
- [Import/Export](/docs/IMPORT_EXPORT.md)
|
||||||
|
|
||||||
|
How to import data in to Baby Buddy and export data from it (easily!).
|
||||||
|
|
||||||
|
|
||||||
|
- [API](/docs/API.md)
|
||||||
|
|
||||||
|
Information about Baby Buddy's robust API.
|
||||||
|
|
||||||
|
|
||||||
|
- [Contributing](/docs/CONTRIBUTING.md)
|
||||||
|
|
||||||
|
How to contribute to Baby Buddy as a developer or translator.
|
||||||
Loading…
Reference in New Issue