1. About
2. REST API Documentation
3. Development
   • Starting from the scratch
   • Daily operations
   • Other operations and issues
   • Docker-related directories
   • Useful resources

About

This is server application for PrzypisPowszechny client - the browser extension for enhancing websites with annotations available to the visitors at the very moment of reading.

To see how the extension works go to about section in the client repository.

REST API Documentation

Check swagger documentation of the latest release.

Development

Starting from the scratch

Install docker compose

$ sudo apt install docker-compose

To run docker as non-root (you live without it, but it's saves a bit of effort with sudo typing everyday):

$ sudo groupadd docker
$ sudo usermod -aG docker $USER

# Now log out and log in

( From docker docs - this creates docker group and add your user to group )

Let's build our image and install python requirements:

$ make build

Once previous step is complete, you just need to run the migrations:

$ make migrate

And run it all:

$ make start-all

Done!

Development environment

.dev.env

Defined the environment for development.

.dev-local.env

Is for setting local development variables that cannot be committed to public repo. Currently consists of:

MAILGUN_API_KEY- Sending emails depends on this setting, so it might not work properly if real private key (but intended for dev, of course) is not set.

FACEBOOK_GRAPH_SECRET - Secret for Facebook Graph API

GOOGLE_OAUTH_SECRET - Secret for Google OAUTH API

File .dev-local.env will be automatically populated with dummy values using .dev-local.env-template. Put there real credentials if you need to use the in the dev environment.

Daily operations

• make test - run tests
• make migrate - run django migrate command to migrate SQL DB
• make makemigrations - run django makemigrations command
• make makemigrations-dry-run - run django makemigrations command in dry-run mode
• make dbshell - open database cmdline
• make shell - open bash shell in container
• make python-shell - open ipython shell with initialized django
• make install - (re)install python requirements using pip install

make help lists all available commands

You can also always bypass make commands and run any command in container :

$ sudo docker-compose run --rm web COMMAND...

Other operations and issues

• Recreating database: just remove docker/data/postgres directory, it is owned by root, so use sudo.

Docker-related directories

• docker/data/postgres - data stored by postgres SQL DB

• docker/data/redis - data stored by redis

• docker/venv/ - python environment created inside web/worker containers Important: do not activate this environment as it was created inside docker container and should be run from it only. This directory is just for the purpose of sharing env files between containers, so the python environments in web/worker stays in sync and thanks to it pip -r requirements has to be run once only.

Useful resources

List of docker resources helpful for better understanding of our dev environment.