Skip to content
This repository was archived by the owner on Mar 4, 2023. It is now read-only.

Commit 88caee2

Browse files
Skycoder42Skycoder42
committed
added server doc
1 parent 8dd24a3 commit 88caee2

File tree

1 file changed

+140
-0
lines changed

1 file changed

+140
-0
lines changed

‎doc/appserver.dox‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
/*!
2+
@page datasync_appserver qdsapp Documentation
3+
4+
@brief The documentation for the backend server application coming with datasync
5+
6+
This page describes how to use appserver. You can follow this document to find out
7+
what you can configure etc.
8+
9+
@tableofcontents
10+
11+
@section datasync_appserver_install Requirements and installation
12+
@subsection datasync_appserver_install_postgre PostgreSQL
13+
All appserver needs as additional setup is a connection to a postgresql database. Simply
14+
install PostgreSQL on your server machine, and create a database (and a user). If you want to use
15+
docker, you can use the [docker image](https://hub.docker.com/_/postgres/) of PostgreSQL. There is
16+
no additional setup needed. Since table creation etc is done by the server itself.
17+
18+
@subsection datasync_appserver_install_qdsapp qdsapp server
19+
For the server, all you need is a standard deployment, e.g. the Qt libraries. The application
20+
itself can be copied from the bin folder of your installation. If you use the libraries from there
21+
as well, it will work fine. Have a look at the deployment pages for details:
22+
- [Linux](https://doc.qt.io/qt-5/linux-deployment.html)
23+
- [Windows](https://doc.qt.io/qt-5/windows-deployment.html)
24+
- [MacOs](https://doc.qt.io/qt-5/osx-deployment.html)
25+
26+
If you install it via one of the package managers, it becomes even easier Check the README for the
27+
support package managers. The server also comes with systemd and launchd files to use it as system
28+
service, and implements the windows service API, so it can be used as windows service as well.
29+
30+
qdsapp is also available as a docker image based on ubuntu rolling. Have a look at
31+
[qdsapp](https://hub.docker.com/r/skycoder42/qdsapp/) on dockerhub.
32+
33+
@section datasync_appserver_usage Usage
34+
For now, there is not really a CLI implemented. This will come as soon as the service API
35+
has been implemented. For now, all you can do is start the server. The configuration is
36+
done via a configuration file
37+
38+
@subsection datasync_appserver_usage_service Using it as a service
39+
TODO comming soon
40+
41+
@subsection datasync_appserver_usage_config The configuration file
42+
The configuration file is all you need to properly setup the server. It's a rather
43+
small config, in the `.ini` file format. On start, the server will search for the
44+
file in usual places. The order used to find the file is as follows:
45+
46+
1. The path defined in the `QDSAPP_CONFIG_FILE` environment variable
47+
2. A file named `qdsappd.conf` (unix), `qdsappsvc.conf` (win) or `qdsapp.conf` (any) in one of the
48+
following locations, ordered by how they are searched:
49+
1. The paths listed in the `QDSAPP_CONFIG_PATH` environment variable, seperated by the system
50+
path seperator
51+
2. The Paths identified by QStandardPaths::ConfigLocation
52+
3. The Paths identified by QStandardPaths::GenericConfigLocation
53+
4. In `/etc/` (unix)
54+
5. In the directoy of the running binary (win)
55+
56+
An simple example for such a config file would be:
57+
@code{.ini}
58+
[general]
59+
loglevel=4
60+
61+
[server]
62+
host=localhost
63+
port=4242
64+
65+
[database]
66+
host=localhost
67+
port=15432
68+
password=baum42
69+
@endcode
70+
71+
The next sections describe the different parts of the configuration file
72+
73+
@subsubsection datasync_appserver_usage_config_general The `general` section
74+
The general section contains stuff to globally configure the server.
75+
76+
Key | Type | Default value | Describtion
77+
--------------------|-----------|-------------------------------|-------------
78+
threads/count | integer | QThread::idealThreadCount() | The maximum of threads the server can use in it's threadpool
79+
threads/expire | integer | 10 | The timeout (in minutes) after which unused threads expire and get removed (Every thread has it's own database connection)
80+
livesync | bool | true | Enable or disable live synchronization (change events for clients)
81+
cleanup/interval | integer | 90 | The number of days a device must be offline to be seen as inactive and thus must be removed
82+
cleanup/auto | bool | true | Enable or disable the automatic removal of devices that are inactive (See cleanup/interval)
83+
quota/limit | integer | 10485760 (10 MB) | The limit in bytes each account can store on the server at most. This is only temporal storage and thus can be kept small
84+
quota/force | bool | false | If enabled and the interval changes, all accounts that have more data then the quota limit are deleted
85+
loglevel | integer | 3 (release), 4 (debug) | The loglevel. The levels are: 0 (nothing), 1 (critical), 2 (warning), 3 (info), 4 (debug)
86+
87+
@subsubsection datasync_appserver_usage_config_database The `database` section
88+
This section is used to set up the database connection.
89+
90+
Key | Type | Default value | Describtion
91+
--------------------|-----------|---------------------------------------|-------------
92+
driver | string | "QPSQL" | The database driver to use. Leave out for PostgreSQL
93+
name | string | QCoreApplication::applicationName() | The name of the database to connect to
94+
host | string | "localhost" | The host to connect to
95+
port | integer | 5432 | The port to connect to
96+
username | string | "" | The username to use
97+
password | string | "" | The password for that username
98+
options | string | "" | Additional database options. See QSqlDatabase::setConnectOptions
99+
keepaliveInterval | integer | 5 | The interval (in minutes) to send keepalive queries in for the event connection
100+
101+
@subsubsection datasync_appserver_usage_config_server The `server` section
102+
This section is used to set up the websocker server. This part is what
103+
clients will connect to.
104+
105+
Key | Type | Default value | Describtion
106+
------------------------|-----------|---------------------------------------|-------------
107+
name | string | QCoreApplication::applicationName() | The servers name, presented in the websocket handshake
108+
host | string | "0.0.0.0" (any) | The host address to listen on. Can be used to limit access
109+
port | integer | 0 (random) | The port to bind to. If 0, a random port is choosen
110+
secret | string | "" | The server secret. All clients need to pass it if the want to connect. If left empty, no secret is required. See QtDataSync::RemoteConfig::Secret
111+
idleTimeout | integer | 5 | A timeout (in minutes) after which a client is automatically disconnected if he did not send the idle ping
112+
uploads/limit | integer | 10 | The maximum number of parallel uploads from a client
113+
downloads/limit | integer | 20 | The maximum number of parallel downloads to a client
114+
downloads/threshold | integer | 10 | A threshold of "free" download spots. Only if a client has less the (limit - threshold) active downloads, new downloads are started
115+
wss | bool | false | Enable a secure (SSL) server. If you set it to true, the other wss/ fields need to be set as well
116+
wss/pfx | string | "" | A path to a PKCS#12 file, containing the certificate to use by the server, as well as the private key
117+
wss/pass | string | "" | The password for the PKCS#12 file
118+
119+
@note The `downloads/limit` and `downloads/threshold` care used to optimize database access. Instead
120+
of sending one dataset at a time, they are packed into batches. This speeds up the whole process
121+
and reduces the load on the database. The two can be used to tune that behaviour.
122+
123+
@section datasync_appserver_cleanup The database cleanup
124+
A final note on the (automatic) cleanup. This procedure simply removes all devices that haven't
125+
logged in since a defined number of days. For most cases, this means that the user stopped using
126+
that device or your application. In order to prevent the database from overflowing with garbage
127+
data, this cleanup can remove such devices.
128+
129+
For the user this means that if he tries to use that device again he will see an authentication
130+
error and must add the device again to the account just like any new device. In case all devices
131+
got remove, he must create a new account.
132+
133+
Please note that no local data gets lost, as it is possible to keep all local data when creating a
134+
new account or adding a device.
135+
136+
It is also possible to completly disable this setting
137+
`cleanup/auto` to false. In that case only explicit cleanups triggered by explicitly invoking the
138+
service can be performed. It is also possible to simply increase the interval to like 3 years.
139+
This reduces the chances of a user actually using the app again after the timeout.
140+
*/

0 commit comments

Comments
 (0)