Merge pull request #60 from greatest-ape/readme-2022-03-26

Improve README; improve CI comments

.github/actions/test-transfer/entrypoint.sh

@@ -1,8 +1,7 @@
 #!/bin/bash
 # 
-# Test that file transfers work with aquatic_http (with and without TLS)
+# Test that file transfers work over all protocols.
-# aquatic_udp and experimentally aquatic_ws (with TLS).
+#
-# 
 # IPv6 is unfortunately disabled by default in Docker
 # (see sysctl net.ipv6.conf.lo.disable_ipv6)
 

README.md

@@ -21,23 +21,22 @@ of sub-implementations for different protocols:
 
 Features at a glance:
 
-- IPv4 and IPv6 support
-- Optional access control (info hash filtering)
-- Built-in TLS support (HTTP and WebTorrent protocols)
 - Multithreaded design for handling large amounts of traffic
-- All data is stored in-memory, so there is no need to configure a database
+- All data is stored in-memory (no database needed)
+- IPv4 and IPv6 support
+- Supports forbidding/allowing info hashes
+- Built-in TLS support (no reverse proxy needed)
+- Automated CI testing of full file transfers
+- Distributed under Apache-2.0 license
 
 ## Usage
 
-### Prerequisites
-
-- Install Rust with [rustup](https://rustup.rs/) (stable is recommended)
-- Install cmake with your package manager (e.g., `apt-get install cmake`)
-- Clone this git repository and enter it
-
 ### Compiling
 
-Compile the implementations that you are interested in:
+- Install Rust with [rustup](https://rustup.rs/) (latest stable release is recommended)
+- Install cmake with your package manager (e.g., `apt-get install cmake`)
+- Clone this git repository and enter the directory
+- Build the implementations that you are interested in:
 
 ```sh
 # Tell Rust to enable support for all CPU extensions present on current CPU
@@ -50,16 +49,7 @@ cargo build --release -p aquatic_http
 cargo build --release -p aquatic_ws
 ```
 
-### Running
+### Configuring
-
-Unless you're planning to only run `aquatic_udp`, make sure locked memory
-limits are sufficient. You can do this by adding the following lines to
-`/etc/security/limits.conf`, and then logging out and back in:
-
-```
-*    hard    memlock    512
-*    soft    memlock    512
-```
 
 Generate configuration files. They come with comments and differ between protocols.
 
@@ -76,22 +66,8 @@ Note that both `aquatic_http` and `aquatic_ws` require configuring TLS
 certificate and private key files. More details are available in the
 respective configuration files.
 
-Once done, run the tracker:
+For optimal performance, start at least as many `request_workers` as
-
+`socket_workers`.
-```sh
-./target/release/aquatic_udp -c "aquatic-udp-config.toml"
-./target/release/aquatic_http -c "aquatic-http-config.toml"
-./target/release/aquatic_ws -c "aquatic-ws-config.toml"
-```
-
-### Configuration values
-
-Starting more `socket_workers` than `request_workers` is recommended. All
-implementations are quite IO-bound and spend a lot of their time reading from
-and writing to sockets. This is handled by the socket workers, which
-also do parsing, serialisation and access control. They pass announce and
-scrape requests to the request workers, which update internal tracker state
-and pass back responses for sending.
 
 #### Access control
 
@@ -111,9 +87,24 @@ parsing fails, the program exits. Later failures result in in emitting of
 an error-level log message, while successful updates of the access list result
 in emitting of an info-level log message.
 
-## Architectural overview
+### Running
 
-![Architectural overview of aquatic](./documents/aquatic-architecture-2022-02-02.svg)
+If you're running `aquatic_http` or `aquatic_ws`, make sure locked memory
+limits are sufficient. You can do this by adding the following lines to
+`/etc/security/limits.conf`, and then logging out and back in:
+
+```
+*    hard    memlock    512
+*    soft    memlock    512
+```
+
+Once done, start the application:
+
+```sh
+./target/release/aquatic_udp -c "aquatic-udp-config.toml"
+./target/release/aquatic_http -c "aquatic-http-config.toml"
+./target/release/aquatic_ws -c "aquatic-ws-config.toml"
+```
 
 ## Details on implementations
 
@@ -195,9 +186,13 @@ corresponding load test binary:
 ./scripts/run-load-test-ws.sh
 ```
 
-To fairly compare HTTP performance to opentracker, set keepalive to false in
+To fairly compare HTTP performance to opentracker, set `keep_alive` to false in
 `aquatic_http` settings.
 
+## Architectural overview
+
+![Architectural overview of aquatic](./documents/aquatic-architecture-2022-02-02.svg)
+
 ## Copyright and license
 
 Copyright (c) 2020-2022 Joakim Frostegård