diff --git a/README.rst b/README.rst index 4f688797bdfd9d370fa9ad3dc0d741b633c0d1af..b8f73caed8d79b84d01445236c216456994df1dd 100644 --- a/README.rst +++ b/README.rst @@ -2,115 +2,54 @@ AURA Steering: Program Scheduler ================================ -Installation ------------- - -If you want to have quick dev server and already have the *steering-postgres* -container of the *aura-web* repository running, follow the steps outlined in the -*Setting up the configuration* section and do:: - - $ docker build -t steering-django --target dev . - $ docker run --rm -v $(pwd):/aura --network auraweb_auranet steering-django:latest python manage.py migrate - $ docker run -it --rm -v $(pwd):/aura --network auraweb_auranet steering-django:latest python manage.py createsuperuser - $ docker run --rm -p 8000:8000 -v $(pwd):/aura --network auraweb_auranet steering-django:latest - -and log into it at http://127.0.0.1:8000/admin/ with the credentials you have -set in the ``createsuperuser`` step. Once this is done, every other time you -want to start a *steering-django* container, you will only have to use the -last command. - -**Full setup without Docker** is done as described below. - -To get setup you must have the following installed: - -* PostgresSQL (except you are using the aura-web docker container *steering-postgres* for it) -* JPEG library development files -* Python 3.8 or later including development files - -In Debian or Ubuntu (or derivatives) you should be able to achieve this with this command:: - - $ sudo apt-get install postgresql postgresql-contrib libjpeg-dev python3 python3-dev +AURA Steering is the scheduling module, where the actual program schedule of +the whole station is stored as well as all infos regarding single shows and +emissions. +It also acts as an OpenID Connect provider for `dashboard` and `tank`. -Setting up the environment --------------------------- - -Create a virtual environment where the dependencies will live:: - - $ python3.8 -m venv python - $ source python/bin/activate - (python)$ - -Change into the base directory of this software and install the project dependencies:: - - (python)$ pip install -r requirements.txt - -Setting up the configuration ----------------------------- - -Copy the ``.env.example`` file to ``.env`` and change the values accordingly. -You have to at least provide the ``SECRET_KEY`` and the ``DBPASS`` values -for Django to start. The file provides extensive comments on all the settings. -For a developments environment the defaults should be just fine if you use the -*steering-postgres* docker container from the *aura-web* repository. If you -want to create your own database on you local machine, you will have to use -*steering* as the database and user name, or adopt the ``DB*`` values -accordingly. - -Also be aware that there is a ``RUN_IN_DOCKER`` setting that is ``True`` by -default. This should be fine for a production environment where Django is -run inside a container. If you follow these steps here to create your own -development environment you have to set this setting to ``False``. You also -might want to set ``DEBUG`` to ``True`` for your development environment. +Requirements +------------ +- Docker Engine 20.10+ +- Docker Compose 2.2+ -Setting up the database ------------------------ +Quickstart +---------- -Then run:: +First build the services:: - (python)$ python manage.py migrate - (python)$ python manage.py loaddata fixtures/*/*.json + $ docker compose build -Adding an admin user --------------------- +Then, you can setup the database:: -In order to create an admin user (which you will need to login to the webinterface after the next step) run:: + $ docker compose run django ./manage.py migrate - (python)$ python manage.py createsuperuser +And load the fixtures:: -Running a web server --------------------- + $ docker compose run django ./manage.py loaddata fixtures/*/*.json -In development you should run:: +Or, if you prefer, you can just create a super user after setting up the database:: - (python)$ python manage.py runserver + $ docker compose run django python manage.py createsuperuser +Then, you can create a RSA Key and the clients for `dashboard` and `tank`:: -After this you can open http://127.0.0.1:8000/admin in your browser and log in -with the credentials you have chosen in the ``createsuperuser`` command. + $ docker compose run django ./manage.py creatersakey + $ docker compose run django ./manage.py create_oidc_client dashboard public -r "id_token token" -u https://localhost:8080/oidc_callback.html -u https://localhost:8080/oidc_callback_silentRenew.html -p https://localhost:8080/ + $ docker compose run django ./manage.py create_oidc_client tank confidential -r "code" -u https://localhost:8040/auth/oidc/callback -If you are using some placeholder credentials, make sure to change your password -by visiting http://127.0.0.1:8000/admin/auth/user/1/password/ +If you prefer to use the admin interface for this, refer to the [OpenID ClientConfiguration](https://gitlab.servus.at/aura/meta/-/blob/master/docs/administration/oidc-client-config.md#registering-oidc-clients-via-the-admin-interface). -Configuring OpenID Connect clients ----------------------------------- +Finally, you can start the services:: -To make AuRa usable, you have to set up OpenID Connect (OIDC) clients for the -*dashboard* and *tank*, so they can make authenticated requests on behalf of -the user against the *steering* API. + $ docker compose up -To do so, you can either visit the Django admin interface and create an RSA key -as well as two clients, or do so programmatically by running:: +You can then login into the admin interface at http://localhost:8000/admin or use the API at http://localhost:8000/api/v1/ - (python)$ python manage.py creatersakey - (python)$ python manage.py create_oidc_client dashboard public -r "id_token token" -u https://aura-test.o94.at/oidc_callback.html -u https://aura-test.o94.at/oidc_callback_silentRenew.html -p https://aura-test.o94.at/ - (python)$ python manage.py create_oidc_client tank confidential -r "code" -u https://aura-test.o94.at/tank/auth/oidc/callback +Testing +------- -In these examples you will have to *https://aura-test.o94.at* and -*https://aura-test.o94.at/tank_with* with wherever *dashboard* and *tank* are -running in your setup. In a local development environment this might be -something like *http://localhost:8080* and *http://localhost:4000* respectively. +If you want to run the test suite, you can run `pytest` in the container:: -The client id and in case of the tank also the client secret are then needed for -the configuration of those components. + $ docker compose run django pytest