From 84b964f501886b56a8c4ff64dacd85c5dc3557e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Wed, 15 Aug 2018 20:26:15 +0200 Subject: [PATCH] Update documentation --- README.md | 134 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 81 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 8d851e2..41a0f4c 100644 --- a/README.md +++ b/README.md @@ -9,68 +9,71 @@ In order to build the proxy server you need to install the qt default package. apt install qt5-default + +## Build from source Change into the source directory and run following commands - cd nymea-remoteproxy - mkdir build - cd build - qmake ../ - make -j$(nproc) + $ cd nymea-remoteproxy + $ mkdir build + $ cd build + $ qmake ../ + $ make -j$(nproc) In the build directory you can find the resulting library and binary files. If you want to start the proxy server from the build directory, you need to export the library path before starting the application: - $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/libnymea-remoteproxy:$(pwd)/libnymea-remoteproxyclient - $ ./server/nymea-remoteproxy -c ../nymea-remoteproxy/tests/test-certificate.crt -k ../nymea-remoteproxy/tests/test-certificate.key + $ ./server/nymea-remoteproxy -c ../nymea-remoteproxy/nymea-remoteproxy.conf -## AWS SDK - -Get the latest source code and build dependecies - - $ apt update - $ apt install git build-essential cmake libcurl4-openssl-dev libssl-dev uuid-dev zlib1g-dev libpulse-dev - - $ git clone https://github.com/aws/aws-sdk-cpp.git - -Create the build and install folder - - $ cd aws-sdk-cpp - $ mkdir -p build/install - $ cd build - - $ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_ONLY="lambda" -DCMAKE_INSTALL_PREFIX=$(pwd)/install ../ - $ make -j$(nproc) - -Install build output into install directory - - $ make install - -#### Building debian package - - $ git clone https://github.com/aws/aws-sdk-cpp.git - $ cd aws-sdk-cpp - - $ git clone git@gitlab.guh.io:cloud/aws-sdk-cpp-debian.git debian +## Build debian package + $ apt install crossbuilder + $ cd nymea-remoteproxy $ crossbuilder - # Install +## From repository +There is a public version available in the nymea repository. + + $ apt install nymea-remoteproxy nymea-remoteproxy-client + +This will install a systemd service called `nymea-remoteproxy.service` and the client application for testing. + +## From build directory + +Simply run following command in the build dir: + + $ sudo make install # Configure +The package will deliver a default configuration file with following content: + + name=nymea-remoteproxy + writeLogs=false + logFile=/var/log/nymea-remoteproxy.log + certificate=/etc/ssl/certs/ssl-cert-snakeoil.pem + certificateKey=/etc/ssl/private/ssl-cert-snakeoil.key + + [WebSocketServer] + host=0.0.0.0 + port=443 + + [TcpServer] + host=0.0.0.0 + port=80 # Test In order to run the test, you can call `make check` in the build directory or run the resulting executable: - $ nymea-remoteproxy-tests + $ nymea-remoteproxy-tests-offline + $ nymea-remoteproxy-tests-online ## Test coverage report @@ -83,12 +86,12 @@ If you want to create a line coverage report from the tests simply run following The resulting coverage report will be place in the `coverage-html` directory. -# Usage +# Server usage In order to get information about the server you can start the command with the `--help` parameter. $ nymea-remoteproxy --help - + Usage: nymea-remoteproxy [options] The nymea remote proxy server. This server allowes nymea-cloud users and registered nymea deamons to establish a tunnel connection. @@ -100,21 +103,21 @@ In order to get information about the server you can start the command with the Options: - -h, --help Displays this help. - -v, --version Displays version information. - -l, --logging Write log file to the given logfile. - -s, --server The server address this proxy will - listen on. Default is 127.0.0.1 - -p, --port The proxy server port. Default is - 1212 - -c, --certificate The path to the SSL certificate used - for this proxy server. - -k, --certificate-key The path to the SSL certificate key - used for this proxy server. - -a, --authentication-server The server url of the AWS - authentication server. + -h, --help Displays this help. + -v, --version Displays version information. + -l, --logging Write log file to the given logfile. + -d, --development Enable the development mode. This + enabled the server assumes there are + static AWS credentials provided to + aws-cli. + -m, --mock-authenticator Start the server using a mock + authenticator which returns always true. + -c, --configuration The path to the proxy server + configuration file. The default is + ~/.config/nymea/nymea-remoteproxy.conf + --verbose Print more verbose. + - # Server API Once a client connects to the proxy server, he must authenticate him self by passing the token received from the nymea-cloud mqtt connection request. @@ -301,6 +304,31 @@ Once the other client is here and ready, the server will send a notification to "status": "success" } +# Client usage + +The client allowes you to test the proxy server and create a dummy client for testing the connection. + + + nymea-remoteproxy-client --help + Usage: nymea-remoteproxy-client [options] + + The nymea remote proxy server client application. This client allowes to test a server application as client perspective. + + Server version: 0.0.1 + API version: 0.1 + + Copyright © 2018 Simon Stürz + + + Options: + -h, --help Displays this help. + -v, --version Displays version information. + -t, --token The AWS token for authentication. + -a, --address
The proxy server host address. Default 127.0.0.1 + -p, --port The proxy server port. Default 1212 + + + # License