docs/install.md

   1 Installing
   2 ==========
   3
   4 This is not very polished or well-documented yet.
   5
   6 The `Makefile` has a `deploy` target which shows how things work on
   7 chiark.
   8
   9 You will need to write a `server-config.toml`.  There is not currently
  10 any documentation for that.  But there are some examples.  Consider
  11 looking at `server-test.toml` in the toplevel, or one of the config
  12 files made by the tests, in `tmp/*/server-config.toml`.
  13
  14 The config is a TOML file, which is read using Rust Serde.  You can
  15 get at least a list of fields by looking at the Rustdoc-generated "API
  16 doc" for the type `otter::config::ServerConfigSpec`, which is probably
  17 in `target/doc/otter/config/struct.ServerConfigSpec.html`.
  18
  19 Here is a copy of the config file from chiark.  As you can see I am
  20 running Otter as an "application server".  My usual Apache
  21 configuration handles the TLS.
  22
  23 ```
  24 http_port = 1323
  25 public_url = "https://otter.chiark.net"
  26 sse_wildcard_url = "https://*.sse.otter.chiark.net"
  27
  28 base_dir = "/volatile/Otter"
  29
  30 save_dir = "/home/Otter/save"
  31 command_socket = "/volatile/Otter/var/command.socket"
  32
  33 ssh_proxy_command = "/volatile/Otter/bin/otter"
  34
  35 [log]
  36 global_level = 'debug'
  37
  38 [log.modules]
  39 'hyper::server' = 'info'
  40 "game::debugreader" = 'info'
  41 ```
  42
  43 The `*.sse` wildcard domain is to work around a bug in the web
  44 facility "server-sent events".  You will probably want one of those
  45 too.  The SSE bug is documented on MDN
  46 <https://developer.mozilla.org/en-US/docs/Web/API/EventSource>.
  47
  48
  49 Final weirdness
  50 ---------------
  51
  52 For running on chiark I build with the Rust target
  53 `x86_64-unknown-linux-musl` which on my system is configured to
  54 produce a completely statically linked binary.  I have this in my
  55 `~/.cargo/config` (in the lesser privsep account):
  56
  57 ```
  58 [target.x86_64-unknown-linux-musl]
  59 rustflags = ["-C", "target-feature=+crt-static"]
  60 # ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
  61 ```
  62
  63
  64 Stability and semver
  65 --------------------
  66
  67 The following interfaces are covered by semantic versioning:
  68
  69  * Save game compatibility (new servers loading old games)
  70  * Command line (new client invoked in old ways) for otter CLI
  71  * Game and table specifications (new software, old specs)
  72  * Library bundles (new servers, old bundles)
  73
  74 Additionally, we will try to support old library bundles indefinitely,
  75 and to break them as little as possible, so long as anyone is using
  76 an older format.g
  77
  78 Of course when a new server is handling a game that uses new features,
  79 old software (eg old management clients) may not cope.
  80
  81 The following are **NOT** covered by semantic versioning:
  82
  83  * Rust library APIs.
  84  * The web templates, AJAX protocol between frontend and backend,
  85    and JavaScript internals.
  86  * Server-client game management protocol (you may need to run the
  87    same version of otter on the client as the server is running)
  88  * Build system interfaces
  89  * Ancillary utilities
  90
  91 This means that the Otter crates do not offer a public stable API.
  92 You may of course use them outside of the Otter project,
  93 but we have no compuction about breaking such use.