From: Jeff Halter Date: Thu, 11 Jul 2024 00:54:15 +0000 (-0700) Subject: Update documentation X-Git-Url: https://git.r.bdr.sh/rbdr/mobius/commitdiff_plain/4fa4a57c4352f703958c3c5cb8dcd2b56cb35882 Update documentation --- diff --git a/Makefile b/Makefile index 241ad21..2832baa 100644 --- a/Makefile +++ b/Makefile @@ -1,105 +1,5 @@ -linux_client_arm_target=dist/mobius_client_linux_arm -build-linux-arm-client: - mkdir $(linux_client_arm_target) ; true - GOOS=linux GOARCH=arm go build -o $(linux_client_arm_target)/mobius-hotline-client cmd/mobius-hotline-client/main.go +server: + go build -o mobius-hotline-server cmd/mobius-hotline-server/main.go -package-linux-arm-client: build-linux-arm-client - cp cmd/mobius-hotline-client/mobius-client-config.yaml $(linux_client_arm_target) - tar -zcvf $(linux_client_arm_target).tar.gz $(linux_client_arm_target) - -linux_client_amd64_target=dist/mobius_client_linux_amd64 -build-linux-amd64-client: - mkdir $(linux_client_amd64_target) ; true - GOOS=linux GOARCH=amd64 go build -o $(linux_client_amd64_target)/mobius-hotline-client cmd/mobius-hotline-client/main.go - -package-linux-amd64-client: build-linux-amd64-client - cp cmd/mobius-hotline-client/mobius-client-config.yaml $(linux_client_amd64_target) - tar -zcvf $(linux_client_amd64_target).tar.gz $(linux_client_amd64_target) - - -linux_server_arm_target=dist/mobius_server_linux_arm -build-linux-arm-server: - mkdir $(linux_server_arm_target) ; true - GOOS=linux GOARCH=arm go build -o $(linux_server_arm_target)/mobius-hotline-server cmd/mobius-hotline-server/main.go - -package-linux-arm-server: build-linux-arm-server - cp -r cmd/mobius-hotline-server/mobius/config $(linux_server_arm_target) - tar -zcvf $(linux_server_arm_target).tar.gz $(linux_server_arm_target) - -linux_server_amd64_target=dist/mobius_server_linux_amd64 -build-linux-amd64-server: - mkdir $(linux_server_amd64_target) ; true - GOOS=linux GOARCH=amd64 go build -o $(linux_server_amd64_target)/mobius-hotline-server cmd/mobius-hotline-server/main.go - -package-linux-amd64-server: build-linux-amd64-server - cp -r cmd/mobius-hotline-server/mobius/config $(linux_server_amd64_target) - tar -zcvf $(linux_server_amd64_target).tar.gz $(linux_server_amd64_target) - -darwin_server_arm64_target=dist/mobius_server_darwin_arm64 -build-darwin-arm64-server: - mkdir $(darwin_server_arm64_target) ; true - GOOS=darwin GOARCH=arm64 go build -o $(darwin_server_arm64_target)/mobius-hotline-server cmd/mobius-hotline-server/main.go - -package-darwin-arm64-server: build-darwin-arm64-server - cp -r cmd/mobius-hotline-server/mobius/config $(darwin_server_arm64_target) - tar -zcvf dist/mobius_server_darwin_arm64.tar.gz $(darwin_server_arm64_target) - -darwin_client_arm64_target=dist/mobius_client_darwin_arm64 -build-darwin-arm64-client: - mkdir $(darwin_client_arm64_target) ; true - GOOS=darwin GOARCH=arm64 go build -o $(darwin_client_arm64_target)/mobius-hotline-client cmd/mobius-hotline-client/main.go - -package-darwin-arm64-client: build-darwin-arm64-client - cp cmd/mobius-hotline-client/mobius-client-config.yaml $(darwin_client_arm64_target) - tar -zcvf dist/mobius_client_darwin_arm64.tar.gz $(darwin_client_arm64_target) - -darwin_server_amd64_target=dist/mobius_server_darwin_amd64 -build-darwin-amd64-server: - mkdir $(darwin_server_amd64_target) ; true - GOOS=darwin GOARCH=amd64 go build -o $(darwin_server_amd64_target)/mobius-hotline-server cmd/mobius-hotline-server/main.go - -package-darwin-amd64-server: build-darwin-amd64-server - cp -r cmd/mobius-hotline-server/mobius/config $(darwin_server_amd64_target) - tar -zcvf dist/mobius_server_darwin_amd64.tar.gz $(darwin_server_amd64_target) - -darwin_client_amd64_target=dist/mobius_client_darwin_amd64 -build-darwin-amd64-client: - mkdir $(darwin_client_amd64_target) ; true - GOOS=darwin GOARCH=amd64 go build -o $(darwin_client_amd64_target)/mobius-hotline-client cmd/mobius-hotline-client/main.go - -package-darwin-amd64-client: build-darwin-amd64-client - cp cmd/mobius-hotline-client/mobius-client-config.yaml $(darwin_client_amd64_target) - tar -zcvf dist/mobius_client_darwin_amd64.tar.gz $(darwin_client_amd64_target) - -windows_client_amd64_target=dist/mobius_client_windows_amd64 -build-win-amd64-client: - mkdir $(windows_client_amd64_target) ; true - GOOS=windows GOARCH=amd64 go build -o $(windows_client_amd64_target)/mobius-hotline-client.exe cmd/mobius-hotline-client/main.go - -package-win-amd64-client: build-win-amd64-client - cp cmd/mobius-hotline-client/mobius-client-config.yaml $(windows_client_amd64_target) - zip -r dist/mobius_client_windows_amd64.zip $(windows_client_amd64_target) - -windows_server_amd64_target=dist/mobius_server_windows_amd64 -build-win-server-amd64: - mkdir $(windows_server_amd64_target) ; true - GOOS=windows GOARCH=amd64 go build -o $(windows_server_amd64_target)/mobius-hotline-server.exe cmd/mobius-hotline-server/main.go - -package-win-amd64-server: build-win-server-amd64 - cp -r cmd/mobius-hotline-server/mobius/config $(windows_server_amd64_target) - zip -r dist/mobius_server_windows_amd64.zip $(windows_server_amd64_target) - -all: clean \ - package-win-amd64-server \ - package-win-amd64-client \ - package-darwin-amd64-client \ - package-darwin-amd64-server \ - package-darwin-arm64-client \ - package-darwin-arm64-server \ - package-linux-arm-server \ - package-linux-amd64-server \ - package-linux-arm-client \ - package-linux-amd64-client \ - -clean: - rm -rf dist/* \ No newline at end of file +client: + go build -o mobius-hotline-client cmd/mobius-hotline-client/main.go \ No newline at end of file diff --git a/README.md b/README.md index 41de347..5f2c7b4 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,37 @@ - + # Mobius Mobius is a cross-platform command line [Hotline](https://en.wikipedia.org/wiki/Hotline_Communications) client and server implemented in Golang. -The goal of Mobius server is to make it simple to run a Hotline server on macOS, Linux, and Windows, with full compatibility for all popular Hotline clients. +- **Server Goal:** Make it simple to run a Hotline server on macOS, Linux, and Windows, with full compatibility for all popular Hotline clients. +- **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). -The goal of the Mobius client is to make it fun and easy to connect to multiple Hotline servers through a [cool retro terminal UI](https://github.com/jhalter/mobius/wiki/Mobius-Client-Screenshot-Gallery). -## Getting started +## Installation + +Mobius is distributed through a single binary. + +Depending on your platform and preferences, you can acquire the binary in the following ways: + +### Build from source + +1. Install [Go](https://go.dev) if needed +2. Run `make server` + +### Download pre-built release + +See [Releases](https://github.com/jhalter/mobius/releases) page. + ### Docker -To quickly run a Hotline server with ports forwarded from the host OS to the container, run: +To run a Hotline server with a default, sample configuration with ports forwarded from the host OS to the container: docker run --rm -p 5500:5500 -p 5501:5501 ghcr.io/jhalter/mobius:latest @@ -24,7 +39,9 @@ You can now connect to localhost:5500 with your favorite Hotline client and play 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. -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: +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. + +Then run the docker command with `-v` and `-init` like so: ``` export HLFILES=/home/myuser/hotline-files @@ -46,70 +63,111 @@ To do this, add the `--user` flag to the docker run arguments with a user ID and `--user 1001:1001` -You'll now find a configuration directory on your host OS populated with a default configuration: +### Homebrew + +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. + +To install the server: + + brew install jhalter/mobius-hotline-server/mobius-hotline-server + +After installation `mobius-hotline-server` will be installed at `$HOMEBREW_PREFIX/bin/mobius-hotline-server` and should be in your $PATH. + +The server config directory will be created under `$HOMEBREW_PREFIX/var/mobius`. + +To start the service: + +`brew services start mobius-hotline-server` + + +## Server Configuration + +After you have a server binary, the next step is to configure the server. + +### Configuration directory + +Mobius stores its configuration and server state in a directory tree: ``` -❯ ls -al $HLFILES -total 32 -drwxr-xr-x 8 jhalter staff 256 Jun 12 17:11 . -drwxr-x---+ 49 jhalter staff 1568 Jun 12 17:11 .. --rw-r--r-- 1 jhalter staff 38 Jun 12 17:11 Agreement.txt -drwxr-xr-x 3 jhalter staff 96 Jun 12 17:11 Files --rw-r--r-- 1 jhalter staff 19 Jun 12 17:11 MessageBoard.txt --rw-r--r-- 1 jhalter staff 15 Jun 12 17:11 ThreadedNews.yaml -drwxr-xr-x 4 jhalter staff 128 Jun 12 17:11 Users --rw-r--r-- 1 jhalter staff 313 Jun 12 17:11 config.yaml +config +├── Agreement.txt +├── Files +│   └── hello.txt +├── MessageBoard.txt +├── ThreadedNews.yaml +├── Users +│   ├── admin.yaml +│   └── guest.yaml +├── banner.jpg +└── config.yaml ``` -Edit `config.yaml` to get started personalizing your server. +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: -### Mac OS +`./mobius-hotline-server -init -config example-config-dir` -For Mac OS the easiest path to installation is through Homebrew. +Brew users can find the config directory in `$HOMEBREW_PREFIX/var/mobius`. -#### Client +Within this directory some files are intended to be edited to customize the server, while others are not. -To install the client: +--- - brew install jhalter/mobius-hotline-client/mobius-hotline-client +* 🛠️ Edit this file to customize your server. +* ⚠️ Avoid manual edits outside of special circumstances (e.g. remove offending news content). -Then run `mobius-hotline-client` to get started. +--- -#### Server +🛠️ `Agreement.text` - The server agreement sent to users after they join the server. -To install the server: +🛠️ `Files` - Home of your warez or any other files you'd like to share. - brew install jhalter/mobius-hotline-server/mobius-hotline-server +⚠️ `MessageBoard.txt` - Plain text file containing the server's message board. No need to edit this. -After installation `mobius-hotline-server` will be installed at `$HOMEBREW_PREFIX/bin/mobius-hotline-server` and should be in your $PATH. +⚠️ `ThreadedNews.yaml` - YAML file containing the server's threaded news. No need to edit this. -The server config file directory is under `$HOMEBREW_PREFIX/var/mobius` which by default contains: +⚠️ `Users` - Directory containing user account YAML files. No need to edit this. - /opt/homebrew/mobius/config/MessageBoard.txt - /opt/homebrew/var/mobius/config/config.yaml - /opt/homebrew/var/mobius/config/ThreadedNews.yaml - /opt/homebrew/var/mobius/config/Agreement.txt - /opt/homebrew/var/mobius/config/Users/guest.yaml - /opt/homebrew/var/mobius/config/Users/admin.yaml +🛠️ `banner.jpg` - Path to server banner image. -Edit `/usr/local/var/mobius/config/config.yaml` to change your server name and other settings. +🛠️ `config.yaml` - Edit to set your server name, description, and enable tracker registration. -Edit `/usr/local/var/mobius/config/Agreement.txt` to set your server agreement. -Run `mobius-hotline-server -help` for usage options. +### User accounts -### Linux +The default installation includes two users: -Download a compiled release for your architecture from the Releases page or follow build from source instructions +* guest (no password) +* admin (default password admin). -### Windows +User administration should be performed from a Hotline client. Avoid editing the files under the `Users` directory. - TODO +## Run the server -### Build from source +By default running `mobius-hotline-server` will listen on ports 5500/5501 of all interfaces with info level logging to STDOUT. + +Use the -h or -help flag for a list of options: + +``` +$ mobius-hotline-server -h +Usage of mobius-hotline-server: + -bind int + Base Hotline server port. File transfer port is base port + 1. (default 5500) + -config string + Path to config root (default "/usr/local/var/mobius/config/") + -init + Populate the config dir with default configuration + -interface string + IP addr of interface to listen on. Defaults to all interfaces. + -log-file string + Path to log file + -log-level string + Log level (default "info") + -stats-port string + Enable stats HTTP endpoint on address and port + -version + Print version and exit +``` -To build from source, run: - make all +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) -Then grab your desired build from `dist`