From 8b29bc3847c3dddef4d81694fd3a757881285813 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Tue, 19 Sep 2017 09:48:29 +0200 Subject: [PATCH 1/4] Add documentation --- docs/.gitignore | 3 +++ docs/Makefile | 4 ++++ docs/docs/about.md | 4 ++++ docs/docs/custom.css | 4 ++++ docs/docs/img/favicon.ico | Bin 0 -> 5141 bytes docs/docs/index.md | 9 +++++++++ docs/docs/installing.md | 36 +++++++++++++++++++++++++++++++++ docs/docs/usage.md | 7 +++++++ docs/mkdocs.yml | 20 ++++++++++++++++++ docs/requirements.txt | 2 ++ docs/theme_overrides/main.html | 6 ++++++ 11 files changed, 95 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/docs/about.md create mode 100644 docs/docs/custom.css create mode 100644 docs/docs/img/favicon.ico create mode 100644 docs/docs/index.md create mode 100644 docs/docs/installing.md create mode 100644 docs/docs/usage.md create mode 100644 docs/mkdocs.yml create mode 100644 docs/requirements.txt create mode 100644 docs/theme_overrides/main.html 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 0000000000000000000000000000000000000000..05ea9715d3f37434888fb3b16d52b966afc0f125 GIT binary patch literal 5141 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 D%Wtx# literal 0 HcmV?d00001 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/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..4a75ec2 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,20 @@ +site_name: SaltyRTC Server +site_description: Documentation for saltyrtc-server-python. +site_author: Lennart Grahl +copyright: © 2016-2017 Lennart Grahl +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 + - 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 %} From 84cf20f8dedac7014a0976cb9d90010a87cdaf2d Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Tue, 19 Sep 2017 10:08:57 +0200 Subject: [PATCH 2/4] Document creating test certificates --- docs/docs/testcerts.md | 46 ++++++++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 47 insertions(+) create mode 100644 docs/docs/testcerts.md diff --git a/docs/docs/testcerts.md b/docs/docs/testcerts.md new file mode 100644 index 0000000..c12cadb --- /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 5 years: + + $ openssl req \ + -newkey rsa:1024 \ + -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 1825 + +## 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/mkdocs.yml b/docs/mkdocs.yml index 4a75ec2..248c8a8 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -14,6 +14,7 @@ pages: - Guide: - Installing: installing.md - Usage: usage.md + - Test Certificates: testcerts.md - About: about.md theme_dir: theme_overrides extra_css: From 1958b8c62cdc93d3d14f89290de609dac5307cbf Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Wed, 20 Sep 2017 13:02:59 +0200 Subject: [PATCH 3/4] Prevent stupidity --- docs/docs/testcerts.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/testcerts.md b/docs/docs/testcerts.md index c12cadb..ddf7169 100644 --- a/docs/docs/testcerts.md +++ b/docs/docs/testcerts.md @@ -8,10 +8,10 @@ self-signed certificate. ## Generating a Test Certificate Use the following command to create such a certificate, valid for `localhost` -during the next 5 years: +during the next 90 days: $ openssl req \ - -newkey rsa:1024 \ + -newkey rsa:3072 \ -x509 \ -nodes \ -keyout saltyrtc.key \ @@ -23,7 +23,7 @@ during the next 5 years: -config <(cat /etc/ssl/openssl.cnf \ <(printf '[SAN]\nsubjectAltName=DNS:localhost')) \ -sha256 \ - -days 1825 + -days 90 ## Importing From 48b7247094ec0a198be6b3a49aec02f650195d0f Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Wed, 20 Sep 2017 13:04:41 +0200 Subject: [PATCH 4/4] Update author info --- docs/mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 248c8a8..4652f7a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,7 +1,7 @@ site_name: SaltyRTC Server site_description: Documentation for saltyrtc-server-python. -site_author: Lennart Grahl -copyright: © 2016-2017 Lennart Grahl +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/