|
| 1 | +--- |
| 2 | +title: With websocket |
| 3 | +--- |
| 4 | + |
| 5 | +With `WEBSOCKET_CONSOLE` set to `true`, logs can be streamed, and commands sent, over a websocket connection. |
| 6 | +The API is available on `/websocket`. |
| 7 | + |
| 8 | +## Password |
| 9 | +A password must be supplied using the `Sec-WebSocket-Protocol` header. This is done by putting `mc-server-runner-ws-v1` in the first slot, and the password in the second. The password can be set with `RCON_PASSWORD` or `WEBSOCKET_PASSWORD`. The latter overwrites the former. Authentication can be disabled with `WEBSOCKET_DISABLE_AUTHENTICATION`. |
| 10 | +??? Example "Examples" |
| 11 | + ```js title="JavaScript example" |
| 12 | + let socket = new WebSocket("http://localhost:80/websocket", ["mc-server-runner-ws-v1", "rcon-password"]); |
| 13 | + ``` |
| 14 | + |
| 15 | +## Allowed origins |
| 16 | +A list of comma-separated allowed origins should be supplied with `WEBSOCKET_ALLOWED_ORIGINS`. Origin checking can be disabled with `WEBSOCKET_DISABLE_ORIGIN_CHECK`. |
| 17 | + |
| 18 | +## Listen address |
| 19 | +The listen address and port can be set with `WEBSOCKET_ADDRESS` (defaults to `0.0.0.0:80`), but it's recommended to listen on all interfaces when running in Docker. |
| 20 | + |
| 21 | +## Log history |
| 22 | +When a connection is established, the last 50 (by default, configurable with `WEBSOCKET_LOG_BUFFER_SIZE`) log lines are sent with a `logHistory` type message. |
| 23 | + |
| 24 | +??? tip "Tip: Remember to forward the websocket port on the host" |
| 25 | + |
| 26 | + ```yaml title="compose.yaml" |
| 27 | + services: |
| 28 | + mc: |
| 29 | + ports: |
| 30 | + - '25565:25565' |
| 31 | + - '80:80' |
| 32 | + ``` |
| 33 | + |
| 34 | +## Environment variables |
| 35 | +| Environment Variable | Usage | Default | |
| 36 | +| ---------------------------------- | ---------------------------------------------------------- | ------------ | |
| 37 | +| `WEBSOCKET_CONSOLE` | Allow remote shell over websocket | `false` | |
| 38 | +| `WEBSOCKET_ADDRESS` | Bind address for websocket server | `0.0.0.0:80` | |
| 39 | +| `WEBSOCKET_DISABLE_ORIGIN_CHECK` | Disable checking if origin is trusted | `false` | |
| 40 | +| `WEBSOCKET_ALLOWED_ORIGINS` | Comma-separated list of trusted origins | ` ` | |
| 41 | +| `WEBSOCKET_PASSWORD` | Password will be the same as RCON_PASSWORD if unset | ` ` | |
| 42 | +| `WEBSOCKET_DISABLE_AUTHENTICATION` | Disable websocket authentication | `false` | |
| 43 | +| `WEBSOCKET_LOG_BUFFER_SIZE` | Number of log lines to save and send to connecting clients | `50` | |
| 44 | + |
| 45 | +## API Schema |
| 46 | +```ts title="API Schema" |
| 47 | +interface StdinMessage { |
| 48 | + type: "stdin"; |
| 49 | + data: string; |
| 50 | +} |
| 51 | + |
| 52 | +interface StdoutMessage { |
| 53 | + type: "stdout"; |
| 54 | + data: string; |
| 55 | +} |
| 56 | + |
| 57 | +interface StderrMessage { |
| 58 | + type: "stderr"; |
| 59 | + data: string; |
| 60 | +} |
| 61 | + |
| 62 | +interface LogHistoryMessage { |
| 63 | + type: "logHistory"; |
| 64 | + lines: string[]; |
| 65 | +} |
| 66 | + |
| 67 | +interface AuthFailureMessage { |
| 68 | + type: "authFailure"; |
| 69 | + reason: string; |
| 70 | +} |
| 71 | + |
| 72 | +// Messages sent from Client -> Server |
| 73 | +export type ClientMessage = StdinMessage; |
| 74 | + |
| 75 | +// Messages sent from Server -> Client |
| 76 | +export type ServerMessage = |
| 77 | + | StdoutMessage |
| 78 | + | StderrMessage |
| 79 | + | LogHistoryMessage |
| 80 | + | AuthFailureMessage; |
| 81 | +``` |
0 commit comments