steve
/
mybuddy
mirror of https://github.com/snachodog/mybuddy.git
1
0
Fork 0
Code Issues 3 Packages Projects 1 Releases Wiki Activity

Use named code blocks throughout documentation

This commit is contained in:
Christopher C. Wells 2022-05-28 13:47:48 -07:00
parent f95edd8957
commit e4345b03e7
5 changed files with 234 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
docs/api.md
View File

@ -61,13 +61,18 @@ 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": [...]
}
```shell
curl -X GET 'https://[...]/api/changes/?limit=5&offset=10' -H 'Authorization: Token [...]'
```
```json
{
"count": 20,
"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.
@ -75,35 +80,48 @@ 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
}
```shell
curl -X GET https://[...]/api/children/gregory-hill/ -H 'Authorization: Token [...]'
```
```json
{
"id":3,
"first_name":"Gregory",
"last_name":"Hill",
"birth_date":"2020-02-11",
"slug":"gregory-hill",
"picture":null
}
```
```shell
curl -X GET https://[...]/api/sleep/1/ -H 'Authorization: Token [...]'
```
```json
{
"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":[{...}]
}
```json
{
"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.
@ -126,34 +144,36 @@ 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"
]
}
```json
{
"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
@ -267,11 +287,13 @@ 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/
```shell
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
@ -291,7 +313,9 @@ 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 [...]'
```shell
curl -X DELETE https://[...]/api/changes/947/ -H 'Authorization: Token [...]'
```
### Response

42
docs/contributing/development-environment.md
View File

@ -19,45 +19,63 @@ information and steps below to set up a local development environment for Baby B
1. Install required Python packages, including dev packages
pipenv install --three --dev
- If this fails, install `libpq-dev` (e.g. `sudo apt install libpq-dev`) and try again.
```shell
pipenv install --three --dev
```
If this fails, install `libpq-dev` (e.g. `sudo apt install libpq-dev`) and try again.
1. Installed Node 14.x (if necessary)
nvm install 14
```shell
nvm install 14
```
1. Activate Node 14.x
nvm use
```shell
nvm use
```
1. Install Gulp CLI
npm install -g gulp-cli
```shell
npm install -g gulp-cli
```
1. Install required Node packages
npm install
```shell
npm install
```
1. Set, at least, the `DJANGO_SETTINGS_MODULE` environment variable
export DJANGO_SETTINGS_MODULE=babybuddy.settings.development
```shell
export DJANGO_SETTINGS_MODULE=babybuddy.settings.development
```
This process will differ based on the host OS. The above example is for
Linux-based systems. See [Configuration](../setup/configuration.md) for other
settings and methods for defining them.
1. Migrate the database
gulp migrate
```shell
gulp migrate
```
1. Create cache table
gulp createcachetable
```shell
gulp createcachetable
```
1. Build assets and run the server
gulp
```shell
gulp
```
This command will also watch for file system changes to rebuild assets and
restart the server as needed.

4
docs/contributing/pull-requests.md
View File

@ -22,7 +22,9 @@ must also be updated to reflect the change. This is necessary because hosting en
do not provide adequate support for pipenv. To update the `requirements.txt` file to be in
sync with the `Pipenv` file run:
pipenv lock -r > requirements.txt
```shell
pipenv requirements > requirements.txt
```
Add and commit the changes to the `requirements.txt` file.

188
docs/setup/deployment.md
View File

@ -34,7 +34,7 @@ See [HTTPS/SSL configuration](ssl.md) for information on how to secure Baby Budd
For doing administrative work within the LSIO container, setting an environment variable may be necessary.
For example:
```
```shell
docker exec -it babybuddy /bin/bash
export DJANGO_SETTINGS_MODULE="babybuddy.settings.base"
python3 /app/babybuddy/manage.py clearsessions
@ -47,18 +47,22 @@ python3 /app/babybuddy/manage.py clearsessions
For manual deployments to Heroku without using the "deploy" button, make sure to
create the following settings before pushing:
heroku config:set DISABLE_COLLECTSTATIC=1
heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku
heroku config:set SECRET_KEY=<CHANGE TO SOMETHING RANDOM>
heroku config:set TIME_ZONE=<DESIRED DEFAULT TIMEZONE>
```shell
heroku config:set DISABLE_COLLECTSTATIC=1
heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku
heroku config:set SECRET_KEY=<CHANGE TO SOMETHING RANDOM>
heroku config:set TIME_ZONE=<DESIRED DEFAULT TIMEZONE>
```
See [Configuration](configuration.md) for other settings that can be controlled
by `heroku config:set`.
After an initial push, execute the following commands:
heroku run python manage.py migrate
heroku run python manage.py createcachetable
```shell
heroku run python manage.py migrate
heroku run python manage.py createcachetable
```
## Manual
@ -80,117 +84,143 @@ and any number of children).
1. Install system packages
sudo apt-get install python3 python3-pip nginx uwsgi uwsgi-plugin-python3 git libopenjp2-7-dev libpq-dev
```shell
sudo apt-get install python3 python3-pip nginx uwsgi uwsgi-plugin-python3 git libopenjp2-7-dev libpq-dev
```
2. Default python3 to python for this session
alias python=python3
```shell
alias python=python3
```
3. Install pipenv
sudo -H pip3 install pipenv
```shell
sudo -H pip3 install pipenv
```
4. 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
```shell
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
```
5. Move in to the application folder
cd /var/www/babybuddy/public
```shell
cd /var/www/babybuddy/public
```
6. Initiate and enter a Python environment with Pipenv locally.
export PIPENV_VENV_IN_PROJECT=1
pipenv install --three
pipenv shell
```shell
export PIPENV_VENV_IN_PROJECT=1
pipenv install --three
pipenv shell
```
7. 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
```shell
cp babybuddy/settings/production.example.py babybuddy/settings/production.py
editor babybuddy/settings/production.py
```
8. Initiate the application
export DJANGO_SETTINGS_MODULE=babybuddy.settings.production
python manage.py migrate
python manage.py createcachetable
```shell
export DJANGO_SETTINGS_MODULE=babybuddy.settings.production
python manage.py migrate
python manage.py createcachetable
```
9. 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
```shell
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
```
10. Create and configure the uwsgi app
sudo editor /etc/uwsgi/apps-available/babybuddy.ini
```shell
sudo editor /etc/uwsgi/apps-available/babybuddy.ini
```
Example config:
Example config:
```ini
[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.
See [Subdirectory configuration](subdirectory.md) for additional configuration
required if Baby Buddy will be hosted in a subdirectory of another server.
```ini
[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.
See [Subdirectory configuration](subdirectory.md) for additional configuration
required if Baby Buddy will be hosted in a subdirectory of another server.
11. Symlink config and restart uWSGI:
sudo ln -s /etc/uwsgi/apps-available/babybuddy.ini /etc/uwsgi/apps-enabled/babybuddy.ini
sudo service uwsgi restart
```shell
sudo ln -s /etc/uwsgi/apps-available/babybuddy.ini /etc/uwsgi/apps-enabled/babybuddy.ini
sudo service uwsgi restart
```
12. Create and configure the nginx server
sudo editor /etc/nginx/sites-available/babybuddy
```shell
sudo editor /etc/nginx/sites-available/babybuddy
```
Example config:
```nginx
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.
See [Subdirectory configuration](subdirectory.md) for additional configuration
required if Baby Buddy will be hosted in a subdirectory of another server.
Example config:
```nginx
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.
See [Subdirectory configuration](subdirectory.md) for additional configuration
required if Baby Buddy will be hosted in a subdirectory of another server.
14. Symlink config and restart NGINX:
sudo ln -s /etc/nginx/sites-available/babybuddy /etc/nginx/sites-enabled/babybuddy
sudo service nginx restart
```shell
sudo ln -s /etc/nginx/sites-available/babybuddy /etc/nginx/sites-enabled/babybuddy
sudo service nginx restart
```
15. That's it (hopefully)!

4
docs/setup/proxy.md
View File

@ -29,7 +29,9 @@ protected requests to succeed.
Note: multiple origins can be added by separating origins with commas. E.g.:
CSRF_TRUSTED_ORIGINS=https://baby.example.com,https://baby.example.org
```shell
CSRF_TRUSTED_ORIGINS=https://baby.example.com,https://baby.example.org
```
### [`SECURE_PROXY_SSL_HEADER`](../configuration#secure_proxy_ssl_header)