git.r.bdr.sh - rbdr/mobius/blob - README.md

   1 <!--<picture>
   2   <source media="(prefers-color-scheme: dark)" srcset="dark_logo.png">
   3   <source media="(prefers-color-scheme: light)" srcset="light_logo.png">
   4   <img src="dark_logo.png" alt="Mobius Logo">
   5 </picture>
   6 -->
   7
   8 # Mobius
   9
  10 Mobius is a cross-platform command line [Hotline](https://en.wikipedia.org/wiki/Hotline_Communications) server implemented in Golang.
  11
  12 - **Project Goal:** Make it simple to run a Hotline server on macOS, Linux, and Windows, with full compatibility for all popular Hotline clients.
  13
  14
  15 ## Installation
  16
  17 Mobius is distributed through a single binary.
  18
  19 Depending on your platform and preferences, you can acquire the binary in the following ways:
  20
  21 ### Build from source
  22
  23 1. Install [Go](https://go.dev) if needed
  24 2. Run `make server`
  25
  26 ### Download pre-built release
  27
  28 See [Releases](https://github.com/jhalter/mobius/releases) page.
  29
  30
  31 ### Docker
  32
  33 To run a Hotline server with a default, sample configuration with ports forwarded from the host OS to the container:
  34
  35         docker run --rm -p 5500:5500 -p 5501:5501 ghcr.io/jhalter/mobius:latest
  36
  37 You can now connect to localhost:5500 with your favorite Hotline client and play around, but all changes will be lost on container restart.
  38
  39 To serve files from the host OS and persist configuration changes, you'll want to set up a [bind mount](https://docs.docker.com/storage/bind-mounts/) that maps a directory from the host into the container.
  40
  41 To do this, create a directory in a location of your choice on the host OS.  For clarity, we'll assign the path to the `HLFILES` environment variable and re-use it.
  42
  43 Then run the docker command with `-v` and `-init` like so:
  44
  45 ```
  46 export HLFILES=/home/myuser/hotline-files
  47 mdkir $HLFILES
  48
  49 sudo docker run \
  50     --pull=always \
  51     --rm \
  52     -p 5500:5500 \
  53     -p 5501:5501 \
  54     -v $HLFILES:/usr/local/var/mobius/config \
  55     ghcr.io/jhalter/mobius-hotline-server:latest \
  56     -init
  57 ```
  58
  59 It's a good security practice to run your server as a non-root user, which also happens to make editing the configuration files easier from the host OS.
  60
  61 To do this, add the `--user` flag to the docker run arguments with a user ID and group ID of a user on the host OS.
  62
  63 `--user 1001:1001`
  64
  65 ### Homebrew
  66
  67 For macOS the easiest path to installation is through Homebrew, as this works around Apple's notarization requirements for downloaded pre-compiled binaries by compiling the binary on your system during brew installation.
  68
  69 To install the server:
  70
  71     brew install jhalter/mobius-hotline-server/mobius-hotline-server
  72
  73 After installation `mobius-hotline-server` will be installed at `$HOMEBREW_PREFIX/bin/mobius-hotline-server` and should be in your $PATH.
  74
  75 The server config directory will be created under `$HOMEBREW_PREFIX/var/mobius`.
  76
  77 To start the service:
  78
  79 `brew services start mobius-hotline-server`
  80
  81
  82 ## Server Configuration
  83
  84 After you have a server binary, the next step is to configure the server.
  85
  86 ### Configuration directory
  87
  88 Mobius stores its configuration and server state in a directory tree:
  89
  90 ```
  91 config
  92 ├── Agreement.txt
  93 ├── Files
  94 │   └── hello.txt
  95 ├── MessageBoard.txt
  96 ├── ThreadedNews.yaml
  97 ├── Users
  98 │   ├── admin.yaml
  99 │   └── guest.yaml
 100 ├── banner.jpg
 101 └── config.yaml
 102 ```
 103
 104 If you acquired the server binary by downloading it or compiling it, this directory doesn't exist yet!  But you can generate it by running the the server with the `-init` flag:
 105
 106 `./mobius-hotline-server -init -config example-config-dir`
 107
 108 Brew users can find the config directory in `$HOMEBREW_PREFIX/var/mobius`.
 109
 110 Within this directory some files are intended to be edited to customize the server, while others are not.
 111
 112 ---
 113
 114 * 🛠️ Edit this file to customize your server.
 115 * ⚠️ Avoid manual edits outside of special circumstances (e.g. remove offending news content).
 116
 117 ---
 118
 119 🛠️ `Agreement.text` - The server agreement sent to users after they join the server.
 120
 121 🛠️ `Files` - Home of your warez or any other files you'd like to share.
 122
 123 ⚠️ `MessageBoard.txt` - Plain text file containing the server's message board.  No need to edit this.
 124
 125 ⚠️ `ThreadedNews.yaml` - YAML file containing the server's threaded news.  No need to edit this.
 126
 127 ⚠️ `Users` - Directory containing user account YAML files.  No need to edit this.
 128
 129 🛠️ `banner.jpg` - Path to server banner image.
 130
 131 🛠️ `config.yaml` - Edit to set your server name, description, and enable tracker registration.
 132
 133
 134 ### User accounts
 135
 136 The default installation includes two users:
 137
 138 * guest (no password)
 139 * admin (default password admin).
 140
 141 User administration should be performed from a Hotline client.  Avoid editing the files under the `Users` directory.
 142
 143 ## Run the server
 144
 145 By default running `mobius-hotline-server` will listen on ports 5500/5501 of all interfaces with info level logging to STDOUT.
 146
 147 Use the -h or -help flag for a list of options:
 148
 149 ```
 150 $ mobius-hotline-server -h
 151 Usage of mobius-hotline-server:
 152   -bind int
 153         Base Hotline server port.  File transfer port is base port + 1. (default 5500)
 154   -config string
 155         Path to config root (default "/usr/local/var/mobius/config/")
 156   -init
 157         Populate the config dir with default configuration
 158   -interface string
 159         IP addr of interface to listen on.  Defaults to all interfaces.
 160   -log-file string
 161         Path to log file
 162   -log-level string
 163         Log level (default "info")
 164   -stats-port string
 165         Enable stats HTTP endpoint on address and port
 166   -version
 167         Print version and exit
 168 ```
 169
 170
 171 To run as a systemd service, refer to this sample unit file: [mobius-hotline-server.service](https://github.com/jhalter/mobius/blob/master/cmd/mobius-hotline-server/mobius-hotline-server.service)
 172
 173 ## (Optional) HTTP API
 174
 175 The Mobius server includes an optional HTTP API to perform out-of-band administrative functions.
 176
 177 To enable it, include the `--api-addr` flag with a string defining the IP and port to listen on in the form of `<ip>:<port>`.
 178
 179 Example: `--api-addr=127.0.0.1:5503`
 180
 181 ⚠️ The API has no authentication, so binding it to localhost is a good idea!
 182
 183 #### GET /api/v1/stats
 184
 185 The stats endpoint returns server runtime statistics and counters.
 186
 187 ```
 188 ❯ curl -s localhost:5503/api/v1/stats  | jq .
 189 {
 190   "ConnectionCounter": 0,
 191   "ConnectionPeak": 0,
 192   "CurrentlyConnected": 0,
 193   "DownloadCounter": 0,
 194   "DownloadsInProgress": 0,
 195   "Since": "2024-07-18T15:36:42.426156-07:00",
 196   "UploadCounter": 0,
 197   "UploadsInProgress": 0,
 198   "WaitingDownloads": 0
 199 }
 200 ```
 201
 202 #### GET /api/v1/reload
 203
 204 The reload endpoint reloads the following configuration files from disk:
 205
 206 * Agreement.txt
 207 * News.txt
 208 * Users/*.yaml
 209 * ThreadedNews.yaml
 210 * banner.jpg
 211
 212 Example:
 213
 214 ```
 215 ❯ curl -s localhost:5503/api/v1/reload | jq .
 216 {
 217   "msg": "config reloaded"
 218 }
 219 ```
 220
 221 #### POST /api/v1/shutdown
 222
 223 The shutdown endpoint accepts a shutdown message from POST payload, sends it to to all connected Hotline clients, then gracefully shuts down the server.
 224
 225 Example:
 226
 227 ```
 228 ❯ curl -d 'Server rebooting' localhost:5503/api/v1/shutdown
 229
 230 { "msg": "server shutting down" }
 231 ```