Commit 027c8f78 authored by Konrad Mohrfeldt's avatar Konrad Mohrfeldt ✊
Browse files

update documentation and specifications for APIs

parent 444ac4ea

.gitlab-ci.yml

+12 −0
Original line number Diff line number Diff line
@@ -11,6 +11,18 @@ make_test: 
    - apk add grep make

    - make test



make_docs:

  stage: test

  image: node:lts-alpine

  tags:

    - fast-io

  script:

    - apk add grep make

    - make docs

  artifacts:

    paths:

      - build/docs



make_deb_package:

  stage: deploy

  image: git-registry.hack-hro.de:443/lohro/lohrothek/thekno/build:buster

Makefile

+1 −0
Original line number Diff line number Diff line
@@ -12,5 +12,6 @@ clean:: 
include make.d/app.mk

include make.d/ci.mk

include make.d/deploy.mk

include make.d/docs.mk

include make.d/packaging.mk

include make.d/release.mk

README.md

+32 −9
Original line number Diff line number Diff line 
# thekno

# Thekno



A Vue.js-based media library and stream web app for your community radio.



This project requires *NodeJS* and *npm*. If any of the commands below are

not available on your computer, see the [System Requirements](#system-requirements)

section at the end of this document.

![mockup.jpg](./docs/mockup_640.jpg)





## About



*Thekno* is a [Progressive Web App](https://en.wikipedia.org/wiki/Progressive_web_applications) and a reference implementation for a set of APIs formalized as part of this project.



By implementing these APIs any community radio will be able to offer a Web App for their listeners who will be able to install it similar to a native app. *Thekno* offers a variety of configuration options for providers including live streams, social platforms, content suggestions and more.



## Design Goals



* **Familiarity**



  *Thekno* should feel and behave like other apps that people use on their phones and desktops.

* **Explorable**



  *Thekno* should encourage users to explore the diversity of your community radio. Both new content and content that matches the user’s interest should be easy to find.



* **Privacy**



  *Thekno* aims for client-storage only and embraces the data sovereignty of its users. Personal information should only be stored on the users device.

  





### Development and Testing Workflow



This project requires *NodeJS* and *npm*. If any of the commands below are

not available on your computer, see the [System Requirements](#system-requirements)

section at the end of this document.



The project uses numerous external dependencies that you can install with the

`npm install` command. After that you can just run `npm run serve` to start up

a development server.



*thekno* ships with fixtures that do not require a backend server, but in case

*Thekno* ships with fixtures that do not require a backend server, but in case

you do want to work with the [Lohrothek REST API](https://git.hack-hro.de/lohro/lohrothek/lohrothek-api)

you can do that. The development server started by `npm run serve` will proxy all

requests to the `/api/` endpoint to `http://localhost:8000/` by default. This
@@ -35,7 +58,7 @@ VUE_APP_APIORIGIN=https://thek.lohro.de npm run serve 
```



You may also use the included docker script `scripts/docker.sh`. It will build

and start *thekno* in an environment similar to those in production. Providing

and start *Thekno* in an environment similar to those in production. Providing

a [custom environment](#environments-and-configuration) is possible with the

`--build-arg` option like this:
@@ -56,18 +79,18 @@ report any errors (that did not exist before 😅). 
VueJS provides a build target out of the box. You can create a build with

`npm run build` and deploy the contents of the `build/dist` directory

afterwards. There is also a `Dockerfile` that can be used to create docker

images (in fact it’s used to automatically deploy *thekno* to our

images (in fact it’s used to automatically deploy *Thekno* to our

[staging server](https://thekno.farbdev.org)).



There will also be a deb package for Debian at a later point.



See [Custom Environments](#custom-environments) for a way to alter the

default behaviour of *thekno*.

default behaviour of *Thekno*.





## Environments and Configuration



*thekno* supports extensive environment runtime configuration. See the

*Thekno* supports extensive environment runtime configuration. See the

[Environment Configuration](./docs/environment-configuration.md) document for

more information on this topic.

docs/apis/common/README.md

0 → 100644
+2 −0
Original line number Diff line number Diff line 
It would be nice to re-arrange this into a RAML library but support for this 

feature seems to be very buggy in raml2html so we have to fallback to includes :(.

docs/apis/common/resource-types.raml

0 → 100644
+17 −0
Original line number Diff line number Diff line 
collection:

  get:

    displayName: Retrieve <<itemType | !pluralize>>

    description: Retrieves a list of <<itemType | !pluralize>>.

    is:

      - paged:

          itemType: <<itemType>>



item:

  get:

    displayName: Retrieve <<itemType>>

    description: Retrieves a single <<itemType>>.

    responses:

      200:

        body:

          application/json:

            type: <<itemType>>