Skip to content

Commit 892f99a

Browse files
committed
chore: update readme for better docker instructions
1 parent e95e8c8 commit 892f99a

1 file changed

Lines changed: 97 additions & 46 deletions

File tree

README.md

Lines changed: 97 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
# tcprcon-cli
22

33
- [tcprcon-cli](#tcprcon-cli)
4-
- [Local Development](#local-development)
54
- [Features](#features)
65
- [Installation](#installation)
76
- [Binary](#binary)
87
- [Docker](#docker)
8+
- [Basic Usage](#basic-usage)
9+
- [Persistent Configuration (Profiles)](#persistent-configuration-profiles)
10+
- [Shell Alias (Optional)](#shell-alias-optional)
911
- [Go](#go)
1012
- [Windows](#windows)
1113
- [Usage](#usage)
@@ -14,11 +16,15 @@
1416
- [Keepalive (Pulse)](#keepalive-pulse)
1517
- [Using Environment Variable for Password](#using-environment-variable-for-password)
1618
- [Configuration Profiles](#configuration-profiles)
19+
- [Saving a Profile](#saving-a-profile)
20+
- [Loading a Profile](#loading-a-profile)
1721
- [CLI Flags](#cli-flags)
1822
- [Interactive UX](#interactive-ux)
1923
- [Protocol Compliance](#protocol-compliance)
24+
- [Local Development](#local-development)
25+
- [Prerequisites](#prerequisites)
26+
- [Getting Started](#getting-started)
2027
- [Using as a Library](#using-as-a-library)
21-
- [Streaming Responses](#streaming-responses)
2228
- [License](#license)
2329

2430

@@ -28,50 +34,6 @@ A fully native RCON client implementation, zero third parties*
2834

2935
![tcprcon-cli demo](.meta/demo.png)
3036

31-
## Local Development
32-
33-
You can use the provided `Makefile` and `compose.yaml` to spin up a local development environment. This will start a Mordhau game server in a container.
34-
35-
### Prerequisites
36-
37-
- Docker and Docker Compose
38-
- Go 1.22+
39-
- Make (optional, but recommended)
40-
41-
### Getting Started
42-
43-
1. **Start a Game Server**:
44-
45-
Beware that the first time you build and run the server it might take a while for its RCON port to be usable, not sure why, but Rust one for example took a few minutes before it was responding, idk.
46-
47-
```bash
48-
make lift-mh-server
49-
```
50-
51-
or
52-
53-
```bash
54-
make lift-rust-server
55-
```
56-
*Note: The server uses `network_mode: host` and may take a few minutes to fully initialize, make sure network_mode is supported by your docker engine*
57-
58-
2. **Build and Run the Client**:
59-
```bash
60-
make run
61-
```
62-
This will build the `tcprcon-cli` binary into `.out/` and execute it against the local server (see step 1) using the default development credentials.
63-
64-
3. **Run Tests**:
65-
```bash
66-
make test
67-
```
68-
69-
4. **Dockerized Client**:
70-
If you prefer to run the client itself inside a container:
71-
```bash
72-
make run-docker
73-
```
74-
7537
## Features
7638

7739
- **Interactive Terminal UI**: full-screen exclusive TUI (like vim or nano) with command history and scrollable output
@@ -89,10 +51,53 @@ Linux binaries are available on the [releases page](https://github.com/UltimateF
8951

9052
### Docker
9153

54+
The Docker image is pulled automatically on first run, so no separate installation step is needed. Just run the container with your desired flags.
55+
56+
#### Basic Usage
57+
58+
All flags and commands from the main [Usage](#usage) section apply here—just prefix them with `docker run`. For example:
59+
9260
```bash
9361
docker run -it ghcr.io/ultimateform/tcprcon-cli:latest --address=192.168.1.100 --port=7778
9462
```
9563

64+
#### Persistent Configuration (Profiles)
65+
66+
**Note:** `tcprcon-cli` supports configuration profiles out of the box (see [Configuration Profiles](#configuration-profiles)). However, when using Docker, profiles are stored inside the container and lost when it exits. To persist profiles across container runs, use a Docker named volume:
67+
68+
```bash
69+
docker run -it \
70+
-v tcprcon-config:/root/.config/tcprcon \
71+
ghcr.io/ultimateform/tcprcon-cli:latest \
72+
--address=192.168.1.100 --port=7778 --save="my_server"
73+
```
74+
75+
Then load the profile in future runs:
76+
77+
```bash
78+
docker run -it --rm \
79+
-v tcprcon-config:/root/.config/tcprcon \
80+
ghcr.io/ultimateform/tcprcon-cli:latest \
81+
--profile="my_server"
82+
```
83+
84+
#### Shell Alias (Optional)
85+
86+
For convenience, create a shell alias in your `~/.bashrc` or `~/.zshrc`:
87+
88+
```bash
89+
# feel free to name it anything else
90+
alias tcprcon-cli='docker run -it --rm -v tcprcon-config:/root/.config/tcprcon ghcr.io/ultimateform/tcprcon-cli:latest'
91+
```
92+
93+
Then reload your shell and use it:
94+
95+
```bash
96+
source ~/.bashrc # or ~/.zshrc
97+
tcprcon-cli --address=192.168.1.100 --port=7778 --save="my_server"
98+
tcprcon-cli --profile="my_server"
99+
```
100+
96101
### Go
97102

98103
```bash
@@ -228,6 +233,52 @@ While `tcprcon-cli` follows the standard Source RCON Protocol, some game servers
228233

229234
For a detailed breakdown of known server quirks and how they are handled, see the [Caveats section in the core library documentation](https://github.com/UltimateForm/tcprcon#caveats).
230235

236+
237+
## Local Development
238+
239+
You can use the provided `Makefile` and `compose.yaml` to spin up a local development environment. This will start a Mordhau game server in a container.
240+
241+
### Prerequisites
242+
243+
- Docker and Docker Compose
244+
- Go 1.22+
245+
- Make (optional, but recommended)
246+
247+
### Getting Started
248+
249+
1. **Start a Game Server**:
250+
251+
Beware that the first time you build and run the server it might take a while for its RCON port to be usable, not sure why, but Rust one for example took a few minutes before it was responding, idk.
252+
253+
```bash
254+
make lift-mh-server
255+
```
256+
257+
or
258+
259+
```bash
260+
make lift-rust-server
261+
```
262+
*Note: The server uses `network_mode: host` and may take a few minutes to fully initialize, make sure network_mode is supported by your docker engine*
263+
264+
2. **Build and Run the Client**:
265+
```bash
266+
make run
267+
```
268+
This will build the `tcprcon-cli` binary into `.out/` and execute it against the local server (see step 1) using the default development credentials.
269+
270+
3. **Run Tests**:
271+
```bash
272+
make test
273+
```
274+
275+
4. **Dockerized Client**:
276+
If you prefer to run the client itself inside a container:
277+
```bash
278+
make run-docker
279+
```
280+
281+
231282
## Using as a Library
232283

233284
See https://github.com/UltimateForm/tcprcon

0 commit comments

Comments
 (0)