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