diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d5c415c --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +*.log +site/ +VENV/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..e471fe5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,4 @@ +all: html + +html: + mkdocs build -v diff --git a/docs/docs/about.md b/docs/docs/about.md new file mode 100644 index 0000000..18f80c0 --- /dev/null +++ b/docs/docs/about.md @@ -0,0 +1,4 @@ +# About SaltyRTC + +For more information about the project, please visit +[saltyrtc.org](http://saltyrtc.org). diff --git a/docs/docs/custom.css b/docs/docs/custom.css new file mode 100644 index 0000000..a20d62b --- /dev/null +++ b/docs/docs/custom.css @@ -0,0 +1,4 @@ +/* Workaround for duplicate headings: https://github.com/mkdocs/mkdocs/issues/318 */ +li.toctree-l3:first-child { + display: none; +} diff --git a/docs/docs/img/favicon.ico b/docs/docs/img/favicon.ico new file mode 100644 index 0000000..05ea971 Binary files /dev/null and b/docs/docs/img/favicon.ico differ diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..e41b20c --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,9 @@ +# SaltyRTC Server + +This is a SaltyRTC server implementation written in Python 3 with asyncio. + +**Contents** + +* [Installing](installing.md) +* [Usage](usage.md) +* [About](about.md) diff --git a/docs/docs/installing.md b/docs/docs/installing.md new file mode 100644 index 0000000..f130111 --- /dev/null +++ b/docs/docs/installing.md @@ -0,0 +1,36 @@ +# Installing + +**Note:** On machines where Python 3 is not the default Python runtime, you +should use `pip3` instead of `pip`. + +## Prerequisites + +You need the following packages installed to be able to run the SaltyRTC +server: + +- python3 +- python3-pip +- libsodium-dev + +## Option A: Installing System-Wide + +Now install `saltyrtc.server` from [PyPI](https://pypi.python.org/): + + $ sudo pip install saltyrtc.server + +## Option B: Installing in a Venv + +If you don't want to install saltyrtc-server-python system-wide, we +recommend using [venv](https://docs.python.org/3/library/venv.html) to create +an isolated Python environment. + + $ python3 -m venv venv + +You can switch into the created virtual environment venv by running this command: + + $ source venv/bin/activate + +While the virtual environment is active, all packages installed using `pip` +will be installed into this environment. + + $ pip install saltyrtc.server diff --git a/docs/docs/testcerts.md b/docs/docs/testcerts.md new file mode 100644 index 0000000..ddf7169 --- /dev/null +++ b/docs/docs/testcerts.md @@ -0,0 +1,46 @@ +# Test Certificates + +To be able to start the SaltyRTC server, you need to specify a TLS key and +certificate. In production you will want to use a certificate signed by a +trusted CA, but for testing purposes, the easiest way is to create a +self-signed certificate. + +## Generating a Test Certificate + +Use the following command to create such a certificate, valid for `localhost` +during the next 90 days: + + $ openssl req \ + -newkey rsa:3072 \ + -x509 \ + -nodes \ + -keyout saltyrtc.key \ + -new \ + -out saltyrtc.crt \ + -subj /CN=localhost \ + -reqexts SAN \ + -extensions SAN \ + -config <(cat /etc/ssl/openssl.cnf \ + <(printf '[SAN]\nsubjectAltName=DNS:localhost')) \ + -sha256 \ + -days 90 + +## Importing + +### Chrome / Chromium + +The best way to import this certificate into Chrome is via the command line: + + $ certutil -d sql:$HOME/.pki/nssdb \ + -A -t "P,," -n saltyrtc-test-ca \ + -i saltyrtc.crt + +Then make sure to restart your browser (or simply visit `chrome://restart`). + +### Firefox + +In Firefox the easiest way to add your certificate to the browser is to start +the SaltyRTC server (e.g. on `localhost` port 8765), then to visit the +corresponding URL via https (e.g. `https://localhost:8765`). Then, in the +certificate warning dialog that pops up, choose "Advanced" and add a permanent +exception. diff --git a/docs/docs/usage.md b/docs/docs/usage.md new file mode 100644 index 0000000..ad76a0c --- /dev/null +++ b/docs/docs/usage.md @@ -0,0 +1,7 @@ +# Usage + +The script `saltyrtc-server` will be automatically installed and provides a +command line interface for the server. Run the following command to see usage +information: + + $ saltyrtc-server --help diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..4652f7a --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,21 @@ +site_name: SaltyRTC Server +site_description: Documentation for saltyrtc-server-python. +site_author: Lennart Grahl, Danilo Bargen +copyright: © 2016-2017 saltyrtc-server-python contributors +theme: readthedocs +repo_url: https://github.com/saltyrtc/saltyrtc-server-python +edit_uri: edit/master/docs/docs/ +markdown_extensions: + - smarty + - toc: + permalink: False +pages: + - Home: index.md + - Guide: + - Installing: installing.md + - Usage: usage.md + - Test Certificates: testcerts.md + - About: about.md +theme_dir: theme_overrides +extra_css: + - custom.css diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..7d2e926 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs==0.16.3 +Pygments==2.1.3 diff --git a/docs/theme_overrides/main.html b/docs/theme_overrides/main.html new file mode 100644 index 0000000..7f216cc --- /dev/null +++ b/docs/theme_overrides/main.html @@ -0,0 +1,6 @@ +{% extends "base.html" %} + +{% block site_name %} +Logo + {{ config.site_name }} +{% endblock %}