105 lines
3.0 KiB
Markdown
105 lines
3.0 KiB
Markdown
# HCRA Server
|
|
|
|
This is the server for HamClock Remote Access. It is a Python web app written
|
|
using Tornado.
|
|
|
|
On its own, the server is useless; it requires HamClock, available at
|
|
http://clearskyinstitute.com/ham/HamClock/ (installed on the same machine as
|
|
the HCRA server), and the HCRA client (see `../client`).
|
|
|
|
The server code is in the `ws_server` directory; unless otherwise noted, all
|
|
commands and instructions assume you have `cd`ed into that directory.
|
|
Utilities for server configuration etc. are in the `utils` directory.
|
|
|
|
## Installation
|
|
|
|
The server itself does not need to be installed; it is simply run with
|
|
`python3 wss.py` in this directory. However, it does have some dependencies
|
|
(both Python packages and binaries).
|
|
|
|
### Python packages
|
|
|
|
pip3 install -r requirements.txt
|
|
|
|
### Binaries
|
|
|
|
#### Ubuntu, Mint, possibly Debian, etc.
|
|
|
|
sudo apt install $(cat ubuntu-pkgs.txt)
|
|
|
|
#### Other distros
|
|
|
|
I only have Mint and Ubuntu computers, so I can't give package names for other
|
|
distros. If you get it working on another distro, please create a pull request
|
|
adding instructions to this file!
|
|
|
|
You will need the following:
|
|
|
|
* Python 3
|
|
* `pip` (for Python 3)
|
|
* ImageMagick 6
|
|
* `Xvfb`
|
|
* `xdotool`
|
|
* `xwd`
|
|
|
|
## Backends
|
|
|
|
The server can connect to HamClock in one of two ways; it can either use
|
|
HamClock's built-in port 8080 service, or it can use X11. The X11 method is
|
|
highly recommended when it can be used, because it does not occasionally
|
|
freeze when HamClock is on certain screens like the port 8080 backend does.
|
|
|
|
A variant on the X11 backend, called the SaaS backend, is also available. It
|
|
works the same way, except it starts HamClock on its own and stops it when
|
|
the user disconnects. This is intended for cloud/SaaS environments that may
|
|
run multiple HamClocks for different users.
|
|
|
|
### Port 8080
|
|
|
|
The Port 8080 backend just requires a running instance of 800x480 HamClock.
|
|
|
|
### X11
|
|
|
|
The X11 backend requires 800x480 HamClock to be running on Xvfb at a
|
|
resolution of `800x480x24`.
|
|
|
|
For example:
|
|
|
|
Xvfb :1 -screen 0 800x480x24
|
|
DISPLAY=:1 path-to-hamclock
|
|
|
|
Replace :1 with the desired display number.
|
|
|
|
### SaaS
|
|
|
|
The SaaS backend
|
|
|
|
### Custom
|
|
|
|
If you write your own backend, just put it in the `backends` folder and
|
|
specify its file name (without `.py`) in `conf.txt`. Make sure you don't
|
|
accidentally commit it if you don't want to!
|
|
<!-- TODO: document API -->
|
|
|
|
## `conf.txt`
|
|
|
|
The server will not work without a `conf.txt` file. This file is a
|
|
space-separated table of configuration data. See the included file for a
|
|
reference. (That file will work for testing, but should not be used on an
|
|
Internet-accessible server. The password is `Testing123`. It uses the X11
|
|
backend, `DISPLAY=:1`.)
|
|
|
|
### `backend`
|
|
|
|
Use `x11` for the X11 backend, or `port8080` for the port 8080 backend.
|
|
|
|
### `display`
|
|
|
|
X11 display to use, such as `:1`. Must be the same as the one used for Xvfb
|
|
and HamClock. Has no effect with the `port8080` backend.
|
|
|
|
### `password_argon2`
|
|
|
|
Argon2-hashed password. Use `pwhash.py` (in `utils`, not `ws_server`) to
|
|
generate a hashed password.
|