Commit 3b4de9ff authored by Philipp Markwardt's avatar Philipp Markwardt 🚊

Merge branch '13-add-dokumentation-for-production-hosting'

parents cff29fb0 70ffc35e
Pipeline #2538 passed with stage
in 1 minute and 3 seconds
......@@ -4,31 +4,81 @@ A Vue.js-based media library and stream web app for your community radio.
![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.
_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.
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**
- **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* should feel and behave like other apps that people use on their phones and desktops.
* **Explorable**
_Thekno_ aims for client-storage only and embraces the data sovereignty of its users. Personal information should only be stored on the users device.
*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.
## Setup for Production
* **Privacy**
We provide `deb` packages for Debian based operating systems. We recommend a setup using Debian Buster (or later) and _nginx_ as webserver.
### Quick Setup | Using Debian Packages
First add the LOHRO Repository to your sources and update the repositories. Please notice that it is currently not signed:
```sh
echo "deb http://deb.lohro.de/ unstable main" > /etc/apt/sources.list.d/lohro.list
apt update
```
*Thekno* aims for client-storage only and embraces the data sovereignty of its users. Personal information should only be stored on the users device.
Now install the package _thekno_ and the webserver _nginx_:
```sh
apt install thekno nginx
```
The thekno package contains primary:
- The static html / js / css / fonts files stored in `/usr/share/thekno/html/`
- An nginx configuration snippet `/etc/nginx/snippets/thekno-spa.conf` referencing to this static files and having all usefull webserver options for thekno
- Configuration examples in `/usr/share/doc/thekno/examples/`
- `env-prod.json` as example endpoint configuration
- `nginx-defaultsite.conf` as example nginx confguration using the snippet
So copy the endpoint configuration file to the thekno html root named as _thekno-env.json_:
```sh
cp /usr/share/doc/thekno/examples/env-prod.json /usr/share/thekno/html/thekno-env.json
```
Then edit this file and change your API path to your production backend. Make sure the webserver is able to serve it.
Now copy the nginx configuration example file...
```sh
cp /usr/share/doc/thekno/examples/nginx-defaultsite.conf /etc/nginx/sites-available/thekno.conf
```
... and edit this configuration file (`/etc/nginx/sites-available/thekno.conf`) for your needs.
Now enable the new configuration and reload your nginx:
```sh
ln -s /etc/nginx/sites-available/thekno.conf /etc/nginx/sites-enabled/
service nginx reload
```
Test your setup and find some small bugs and report them :)
## Development and Testing Workflow
This project requires *NodeJS* and *npm*. If any of the commands below are
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.
......@@ -36,7 +86,7 @@ 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
......@@ -58,7 +108,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:
......@@ -66,42 +116,36 @@ a [custom environment](#environments-and-configuration) is possible with the
scripts/docker.sh --build-arg env_file=path/to/my/environment-file.json
```
## Contributions
Contributions are always welcome. Before you push your commits or create
*merge requests* make sure that `npm run lint` and `npm run test` do not
_merge requests_ make sure that `npm run lint` and `npm run test` do not
report any errors (that did not exist before 😅).
Installation
## Builds & Deployment
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.
## System Requirements
This projects requires fairly recent versions of *NodeJS* (v8+) and *npm* (v5.8+).
This projects requires fairly recent versions of _NodeJS_ (v8+) and _npm_ (v5.8+).
Both are bundled with the default distribution available on
[nodejs.org](https://nodejs.org/en/download/).
### Debian Stretch
If you are using Debian Stretch you’ll notice that the distributed `nodejs` package
......@@ -122,16 +166,14 @@ following command:
apt update && apt install -t stretch-backports nodejs npm
```
### Debian Buster
Debian Buster ships with the required versions so that you can just install
the `nodejs` and `npm` packages.
### Other Distributions & Windows
For all other distributions that do not contain the required *NodeJS* and *npm*
For all other distributions that do not contain the required _NodeJS_ and _npm_
packages visit the [download section](https://nodejs.org/en/download/) on the
NodeJS page.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment