Cykel

Basic backend for a mobility sharing service. First steps made at CCCamp 2019, further developed, daily used and tested in the City of Ulm and now maintained by the transportkollektiv.

OpenBike consists of more parts than just cykel - you might want to have a look into the whole OpenBike Project Documentation, which also contains installation guidelines for the other parts and operator documentation for running an OpenBike based sharing system.

Prerequisites

• Python (≥3.7)
• Postgres database with PostGIS extension. (MySQL and SQLite are not supported anymore)
• Redis

Configuration

Create a file .env in the cykel subdirectory, with the following contents:

# insert your own random string here
SECRET_KEY=f2bf0a4e621a16d9eb8253aa7a540f75ed8787b5
# set to 1 to enable DEBUG output, or 0 to disable
DEBUG=1
# configure your database in a format supported by https://github.com/jacobian/dj-database-url
DATABASE_URL=postgis://localhost/cykel
# redis connection, you may only have to change this if your redis doesn't live on the same host
REDIS_URL=redis://localhost:6379/0
# it is recommended to use a DNS alias for localhost, instead of "localhost", for CORS reasons
ALLOWED_HOSTS=lvh.me,localhost
# set the full URL to the frontend
UI_SITE_URL=http://lvh.me:1234/
# CORS origins to whitelist, i.e. the frontend URL (with scheme, without path)
CORS_ORIGIN_WHITELIST=http://lvh.me:1234
# Set to true if cykel runs behind a reverse proxy, so the `X-Forwarded-Proto` header gets interpreted and URLs are built correctly with https
USE_X_FORWARDED_PROTO=true

Install the required packages using pip install -r requirements.txt. It is recommended to use a virtualenv with your choice of tool, e.g. pipenv, in which case you can run pipenv install (and pipenv shell or prefix pipenv run to run commands).

Then run manage.py migrate to create the database tables.

Database configuration for PostgreSQL/PostGIS

You need to enable the following extensions in the cykel database after installing PostGIS:

CREATE EXTENSION postgis;
CREATE EXTENSION postgis_topology;

The DB migration will fail otherwise.

Running the local server

Run manage.py runserver.

Configuring authentication

For the administration interface you can run manage.py createsuperuser to create an user with administrative rights and access the interface at http://localhost:8080/admin.

Then, visit /admin/ and edit the URL of the first Website (/admin/sites/site/1/change/).

Configuring OAuth

Visit /admin/socialaccount/socialapp/add/ (Add Social Application).

For example, for GitHub select "Provider: GitHub", "Name: github", the Client-Id and Secret are shown in the OAuth application creation process at GitHub.

When you create an OAuth2-Application at a provider, you need to enter a callback URL. This URL is in the format https://<host>/auth/<name>/login/callback/.

Update bike location

For updating the current bike location we provide the /api/bike/updatelocation endpoint.

One project which can use this together with TheThingsNetwork is the cykel-ttn adapter. Read the readme in the repository on how to use it - for authentication you need to add a new api key at /admin/rest_framework_api_key/apikey/.

Alternative: using Docker Compose

docker-compose pull
docker-compose up -d --build

To run the migrate.py commands that are shown above, prefix them with docker-compose exec cykel:

docker-compose exec cykel python manage.py migrate
docker-compose exec cykel python manage.py createsuperuser

To use other settings (like ALLOWED_HOSTS) from above, add them to the environment in docker-compose.yml.

Docker Compose runs cykel and voorwiel (one frontend implementation), so you can develop and test with a client right away.

Contributing

We welcome issues and pull requests for new features, bugs or problems you encountered when setting it up. More Documentation or simply small typo fixes are also very appreciated. If you found a vulnerability or other security relevant issue, notify us at openbike @ ulm.dev

For general discussion, feel free to hop into the public matrix channel for openbike and related projects.

Generally, the cykel python/django code follows PEP8. We're using flake8, isort, black and docformatter as style checkers, so those can help you if you're not sure how to format something.

You can run them all at once using make style.

Tests

To get stated with tests, you need to install the development dependencies: pip install -r requirements-dev.txt

If you want to run them on your machine, use pytest. Tests are also automatically run for pull requests.

make will also run all tests.