Django API server for the karrot frontend
There are 3 approaches to getting your developer environment setup:
- single docker container - includes backend, postgres, and redis in one container
- local install - install everything on your system (Arch, Ubuntu, Debian, macOS, OpenSUSE Leap)
- docker-compose setup - includes backend, frontend, mail catcher, postgres, redis, etc..
You can automate your setup with Docker.
Build the docker container:
docker build -t backend .
Run this container, including your most recent source code changes:
docker run -d -p 8000:8000 -v $PWD/foodsaving:/karrot-backend/foodsaving backend
Note 1: This assumes that your terminal's working directory is in the karrot-backend directory, i.e. the directory you cloned from Github. Note 2: Only changes you make in the "foodsaving" directory are included.
The test data are automatically created in the container. You can see log-in details after running this command:
docker logs -f CONTAINER
With this data, you can log in as one of the printed e-mail addresses with password 123
The server is already running in Docker container.
- python3.5 or greater/virtualenv
- postgresql >=9.4
- redis-server
All packages can be obtained from core, extra or community repositories. When queried, chose to install all packets out of base-devel.
sudo pacman -S base-devel python python-pip python-virtualenv postgresql python-redis redis
Afterwards, do the first-time postgres setup (taken from the Arch Linux wiki)
sudo -i -u postgres
initdb --locale en_US.UTF-8 -E UTF8 -D '/var/lib/postgres/data'
By default, Arch Linux does not start the installed services. Do it manually by executing
sudo systemctl start postgresql.service
sudo systemctl start redis.service
You can add them to autostart as well:
sudo systemctl enable postgresql.service
sudo systemctl enable redis.service
As karrot requires relatively recent versions of some packages, using Ubuntu 15.10 or greater is required.
sudo apt-get install git redis-server python3 python3-dev python-virtualenv postgresql postgresql-server-dev-9.4 gcc build-essential g++ libffi-dev libncurses5-dev
For Mac OS, you will need homebrew. With homebrew you can install all packages.
brew install postgresql
initdb /usr/local/var/postgres -E utf8
brew services start postgresql
brew install redis
brew services start redis
All packages should be available in the default repositories repo-oss
and repo-non-oss
.
sudo zypper install python-virtualenv postgresql-devel postgresql python-redis redis
Head over to yunity/foodsaving-docker for further instructions.
Before using any tools from the shell, you need to activate the virtualenv:
source ./env/bin/activate
The manage.py application can be used to perform administrative tasks:
- makemigrations: Create database migrations
- migrate: Apply database migrations
- shell_plus: (requires ipython) for playing in a django python environment
- test: Run automated tests
A swagger description file is generated at /doc. You can pass it to any swagger installation.
In development, you can add and override local settings in
config/local_settings.py
, which is present in .gitignore
and hence out of
version control. If the file is not present, i.e. in production, nothing
happens.
Change the following values in the dictionary DATABASES
in the file local_settings.py (example)
: NAME
, USER
and PASSWORD
. Change also variables INFLUXDB_DATABASE
and DEFAULT_FROM_EMAIL
in local_settings.py (example)
accordingly.
Set your database PostgreSQL
with the correct name and user.
First, initialize the database.
initdb /usr/local/var/postgres
Now, create the user you used in local_settings.py
.
createuser --pwprompt *user_name*
And create the database with the name you used in local_settings.py
.
createdb -O *user_name* -Eutf8 *db_name*
You can run the server with python manage.py runserver
.
Sometimes you will need to create Django migrations.
source env/bin/activate
./manage.py makemigrations
./manage.py migrate
In particular, before you launch your backend for the very first time you will need to execute ./manage.py migrate
to initialize your database.
To contribute, please get in contact with us. We want to follow a pull request / code review cycle as soon as possible but in our early design stages we prefer to work in teams at the same desk. We use
- github issues for development tasks
- Slack as team communication, not only for development
We follow PEP8 with the same rules as the Django project.
As always, the coding style may not apply at some parts.
You can execute flake8
in the repository root to check your code.
Code will only be accepted into master
if it passes the PEP8 test.
A live instance of karrot is running at https://foodsaving.world/. Use https://foodsaving.world/api/ for a browseable API and for API requests.
A session is identified via the sessionid cookie. Additionally, a csrftoken cookie is set with each POST request (initially for the login). To issue any other POST request than a login, you need to provide the contents of the csrftoken cookie in the X-CSRFToken header field. The session cookie is automatically appended to each request by the browser. For more detailled notes on how to implement this in javascript, see https://docs.djangoproject.com/en/1.9/ref/csrf/
On a local setup, you may want to change fsync behaviour to speed up the test running process. You may want to make sure to understand the implications but on a dev machine this should be fine.
Edit /var/lib/postgres/data/postgresql.conf and add or edit
fsync = off
pip-tools is used to manage requirements. To use the latest possible requirements, do:
pip install pip-tools
pip-compile --upgrade
We use PyCharm for development. We have some licenses available for the professional version which includes Django support specifically. The free community edition also works well.
You can use whatever you want of course.
Please set the python interpreter to the virtual env python created during during the setup.
For all those who love Vim, just enable syntax checking and add python and django plugins to Vim. Follow using vim with django.
When editing emails it's useful to be able to see how they will be rendered.
Assuming the server is running you can visit visit localhost:8000/_templates.
To compile the .mjml
templates to .html.jinja2
files you can run:
cd mjml
yarn
./convert
If you want to watch for changes, and support hot reloading then run:
./convert --watch
(refresh your browser after starting the server as the websocket is not reconnecting)
Note: you should never edit .html.jinja2
files directly.
Enjoy! ... oh and be sure to visit https://mjml.io/documentation/#components to find some nice components to use.