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