Skip to content

Commit 336c3e4

Browse files
dnomd343dnomd343
committed
docs: more detailed README
1 parent a232f70 commit 336c3e4

File tree

1 file changed

+201
-46
lines changed

1 file changed

+201
-46
lines changed

‎README.md‎

Lines changed: 201 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,249 @@
11
## Quick Start
22

3-
Start a syncplay service at `tcp/8999` with one command.
3+
Using one command to start the Syncplay service. Yes, it's very simple.
44

55
```bash
6-
docker run -d --network host --restart always --name syncplay dnomd343/syncplay
6+
> docker run --rm --net=host dnomd343/syncplay
7+
Welcome to Syncplay server, ver. 1.7.0
78
```
89

9-
More arguments can be specified.
10+
> Pressing `Ctrl+C` will exit the service.
11+
12+
If there are no accidents, you can fill in the server IP or domain name on the client for verification, the default port is `tcp/8999` . If you can't connect, please check your firewall settings.
13+
14+
In order to run the service better, we can use the following command to make Syncplay run in the background and keep it started.
1015

1116
```bash
12-
docker run -d --network host --restart always --name syncplay dnomd343/syncplay \
13-
--port 12345 --password dnomd343 --motd hello --isolate-room --disable-chat
17+
docker run -d --net=host --restart=always --name=syncplay dnomd343/syncplay
1418
```
1519

16-
You can also use environment variables to specify.
20+
> You can use `docker ps -a` to see the running service, and using `docker rm -f syncplay` to stop the service.
21+
22+
You can add more arguments to achieve customization. For example, we require a password when connecting to the server, prohibit chat, and display a welcome message after entering the room. Use the following commands.
23+
24+
> Note that before pressing Enter, you must execute `docker rm -f syncplay` to remove the original services, otherwise they will conflict.
1725
1826
```bash
19-
docker run -d --network host --restart always --name syncplay \
20-
--env PORT=12345 \
21-
--env PASSWD=dnomd343 \
22-
--env MOTD="Hello World" \
23-
--env ISOLATE=ON \
24-
dnomd343/syncplay
27+
docker run -d --net=host \
28+
--restart=always --name=syncplay \
29+
dnomd343/syncplay --disable-chat \
30+
--password=PASSWD --motd='HELLO WORLD'
2531
```
2632

27-
Enable TLS support of Syncplay server.
33+
The server will be restarted when necessary, or the Docker service or Syncplay may need to be updated. Whether it is expected or not, it is necessary to persist Syncplay at this time, which means that the room data will be saved to disk. You need to choose a working directory to save them, such as `/etc/syncplay/` , execute the following command, the data will be saved to the `rooms.db` file.
2834

2935
```bash
30-
docker run -d --network host --restart always --name syncplay \
31-
--volume /etc/ssl/certs/343.re/:/certs/ dnomd343/syncplay --enable-tls
36+
docker run -d --net=host \
37+
--restart=always --name=syncplay \
38+
--volume /etc/syncplay/:/data/ \
39+
dnomd343/syncplay --persistent
40+
```
41+
42+
This directory has more uses. For example, adding the `--enable-stats` option will enable the statistics function, and the data will be saved to the file `stats.db` in the directory. You can also create a `config.yml` file in the directory and write the configuration parameters in it, Syncplay will automatically read it when it starts, avoiding the need to type a large number of parameters in the command line.
43+
44+
```yaml
45+
# /etc/syncplay/config.yml
46+
password: 'My Password'
47+
persistent: true
48+
enable-stats: true
49+
disable-chat: false
50+
motd: |
51+
Hello, here is a syncplay server.
52+
More information...
3253
```
3354
34-
> The `/etc/ssl/certs/343.re/` folder stores certificates and private key files, and specific introductions and examples will be given below.
55+
When deploying, it's always a good idea to turn on TLS (of course it's not necessary and this step can be skipped), and luckily Syncplay makes it easy to do this. Before starting, you need to prepare a domain name and resolve its DNS to the current server. At the same time, we must have its certificate file.
3556
36-
### Options
57+
Application for a certificate can be made through [`acme.sh`](https://acme.sh/) , [`certbot`](https://certbot.eff.org/) or other reasonable methods. Anyway, you will end up with a private key and a certificate, and Syncplay requires you to provide the following three files.
3758

38-
You can specify the following arguments:
59+
+ `cert.pem` ：The certificate issued by the CA.
60+
+ `chain.pem` ：The certificate chain of CA service.
61+
+ `privkey.pem` ：The private key for the certificate.
3962

40-
+ `--port [PORT]` ：Listening port of Syncplay server, the default is `8999`
63+
For example, in `acme.sh` , you can execute the command like this to save the certificate configuration of the domain name `343.re` to the `/etc/ssl/certs/343.re/` directory.
4164

42-
+ `--motd [MESSAGE]` ：The welcome text after the user enters the room.
65+
```bash
66+
acme.sh --install-cert -d 343.re \
67+
--cert-file /etc/ssl/certs/343.re/cert.pem \
68+
--ca-file /etc/ssl/certs/343.re/chain.pem \
69+
--key-file /etc/ssl/certs/343.re/privkey.pem
70+
```
4371

44-
+ `--password [PASSWD]` ：Authentication when the user connects to the syncplay server.
72+
Now that we are ready, we just need to execute the following command and a more secure and private Syncplay service will be started.
73+
74+
```bash
75+
docker run -d --net=host \
76+
--restart=always --name=syncplay \
77+
--volume /etc/syncplay/:/data/ \
78+
--volume /etc/ssl/certs/343.re/:/certs/ \
79+
dnomd343/syncplay --persistent --enable-tls
80+
```
81+
82+
> Note that the client's server address must match the certificate, otherwise the connection will fail.
83+
84+
It should be noted that unlike some services, Syncplay does not need to be manually restarted when the certificate is updated. It will automatically detect certificate changes and use the latest version. In addition, TLS on the Syncplay server is adaptive, which means that even older versions of clients that do not support TLS can still communicate normally, but note that security encryption will no longer take effect at this time.
85+
86+
## Command-line Arguments
87+
88+
You can customize the Syncplay server by specifying the following command line arguments.
89+
90+
> The following parameters are adjusted for docker and are not exactly the same as [official documentation](https://man.archlinux.org/man/extra/syncplay/syncplay-server.1). Please refer to this when using.
91+
92+
+ `--port [PORT]` ：Listening port of Syncplay server, the default is `8999` .
93+
94+
+ `--password [PASSWD]` ：Authentication when the user connects to the syncplay server, not enabled by default.
95+
96+
+ `--motd [MESSAGE]` ：The welcome text after the user enters the room, not enabled by default.
4597

4698
+ `--salt [SALT]` ：A string used to secure passwords (e.g. Rainbow-tables), defaults to empty.
4799

48-
+ `--random-salt` ：Use a randomly generated salt value, valid when `--salt` is not specified.
100+
+ `--random-salt` ：Use a randomly generated salt value, valid when `--salt` is not specified, not enabled by default.
101+
102+
+ `--isolate-rooms` ：Room isolation enabled, users will not be able to see information from anyone other than their own room, not enabled by default.
103+
104+
+ `--disable-chat` ：Disables the chat feature, not enabled by default.
49105

50-
+ `--isolate-room` ：Room isolation enabled, users will not be able to see information from anyone other than their own room.
106+
+ `--disable-ready` ：Disables the readiness indicator feature, not enabled by default.
51107

52-
+ `--disable-chat` ：Disables the chat feature.
108+
+ `--enable-stats` ：Enable the server statistics feature, the data will be saved in the `stats.db` file, not enabled by default.
53109

54-
+ `--disable-ready` ：Disables the readiness indicator feature.
110+
+ `--enable-tls` ：Enable TLS support, the certificate file needs to be mounted in the `/certs/` directory, including `cert.pem` , `chain.pem` and `privkey.pem` , not enabled by default.
55111

56-
+ `--max-username-length` ：Maximum length of usernames (number of characters).
112+
+ `--persistent` ：Enable room data persistence, the information will be saved to the `rooms.db` file, only valid when `--isolate-rooms` is not specified, not enabled by default.
57113

58-
+ `--max-chat-message-length` ：Maximum length of chat messages (number of characters).
114+
+ `--max-username [N]` ：Maximum length of usernames, default is `150` .
59115

60-
+ `--enable-tls` ：Enable tls support, the certificate directory should be synchronized to `/certs/`, including `cert.pem`, `chain.pem` and `privkey.pem` three files.
116+
+ `--max-chat-message [N]` ：Maximum length of chat messages, default is `150` .
61117

62-
+ `cert.pem` ：The certificate issued by the CA.
63-
+ `chain.pem` ：The certificate chain of CA service.
64-
+ `privkey.pem` ：The private key for the certificate.
118+
+ `--permanent-rooms [ROOM ...]` ：Specifies a list of rooms that will still be listed even if their playlist is empty, only valid when `--persistent` is specified, defaults to empty.
65119

66-
> For example, in [`acme.sh`](https://acme.sh/), they correspond to `--cert-file`, `--ca-file` and `--key-file` respectively, the following is an example of certificate installation.
120+
You can also use the following command to output help information.
67121

68122
```bash
69-
# Export the domain `343.re` to `/etc/ssl/certs/343.re/`
70-
acme.sh --install-cert -d 343.re \
71-
--cert-file /etc/ssl/certs/343.re/cert.pem \
72-
--ca-file /etc/ssl/certs/343.re/chain.pem \
73-
--key-file /etc/ssl/certs/343.re/privkey.pem
123+
> docker run --rm syncplay --help
124+
usage: syncplay [-h] [-p PORT] [--password PASSWORD] [--motd MOTD]
125+
[--salt SALT] [--random-salt] [--isolate-rooms]
126+
[--disable-chat] [--disable-ready] [--enable-stats]
127+
[--enable-tls] [--persistent] [--max-username MAX_USERNAME]
128+
[--max-chat-message MAX_CHAT_MESSAGE]
129+
[--permanent-rooms [PERMANENT_ROOMS ...]]
130+
131+
Syncplay Docker Bootstrap
132+
133+
optional arguments:
134+
-h, --help show this help message and exit
135+
-p PORT, --port PORT listen port of syncplay server
136+
--password PASSWORD authentication of syncplay server
137+
--motd MOTD welcome text after the user enters the room
138+
--salt SALT string used to secure passwords
139+
--random-salt use a randomly generated salt value
140+
--isolate-rooms room isolation enabled
141+
--disable-chat disables the chat feature
142+
--disable-ready disables the readiness indicator feature
143+
--enable-stats enable syncplay server statistics
144+
--enable-tls enable tls support of syncplay server
145+
--persistent enables room persistence
146+
--max-username MAX_USERNAME
147+
maximum length of usernames
148+
--max-chat-message MAX_CHAT_MESSAGE
149+
maximum length of chat messages
150+
--permanent-rooms [PERMANENT_ROOMS ...]
151+
permanent rooms of syncplay server
152+
```
153+
154+
## Configure File
155+
156+
If you configure a lot of options, it will be quite troublesome and error-prone to enter a large number of command line parameters every time you start. At this time, you can write them into the configuration file. Create a `config.yml` file in the working directory. It uses YAML format and supports all parameters in the command line. Syncplay will automatically read and load it when starting, but it should be noted that if the same parameters are specified on the command line, will override the configuration file's options.
157+
158+
```yaml
159+
port: 7999
160+
salt: 'SALT'
161+
random-salt: true
162+
password: 'My Password'
163+
persistent: true
164+
enable-tls: true
165+
enable-stats: true
166+
isolate-rooms: true
167+
disable-chat: true
168+
disable-ready: true
169+
max-username: 256
170+
max-chat-message: 2048
171+
permanent-rooms:
172+
- ROOM_1
173+
- ROOM_2
174+
- ROOM_3
175+
motd: |
176+
Hello, here is a syncplay server.
177+
More information...
178+
```
179+
180+
## Docker Compose
181+
182+
Using `docker-compose` to deploy Syncplay is a more elegant way. You need to create a `docker-compose.yml` configuration file and write the following example.
183+
184+
```yaml
185+
# /etc/syncplay/docker-compose.yml
186+
version: '3'
187+
services:
188+
syncplay:
189+
container_name: syncplay
190+
image: dnomd343/syncplay
191+
network_mode: host
192+
restart: always
193+
volumes:
194+
- ./:/data/
74195
```
75196

76-
You can also specify arguments through environment variables:
197+
We save this file in the `/etc/syncplay/` directory. Since a relative path is used, it is also in the working directory. Execute the command in this directory to start the Syncplay service.
198+
199+
```bash
200+
> docker-compose up
201+
Recreating syncplay ... done
202+
Attaching to syncplay
203+
syncplay | Welcome to Syncplay server, ver. 1.7.0
204+
```
205+
206+
> Adding the `-d` option allows the service to run in the background.
207+
208+
Similarly, you can map the certificate directory to enable TLS functionality, and edit the `config.yml` file to configure more options.
77209

78-
+ `PORT` ：Equivalent to `--port`
210+
## Troubleshooting
79211

80-
+ `SALT` ：Equivalent to `--salt`
212+
If you encounter any errors, please first use the `docker logs syncplay` command to print the process output. It may contain useful error information. You can also output more detailed logs by specifying the environment variable `DEBUG=ON` .
81213

82-
+ `MOTD` ：Equivalent to `--motd`
214+
```bash
215+
> docker run --rm --env DEBUG=ON dnomd343/syncplay
216+
Command line arguments -> Namespace(port=None, password=None, motd=None, salt=None, random_salt=False, isolate_rooms=False, disable_chat=False, disable_ready=False, enable_stats=False, enable_tls=False, persistent=False, max_username=None, max_chat_message=None, permanent_rooms=None)
217+
Parsed arguments -> {}
218+
Syncplay startup arguments -> ['--port', '8999', '--salt', '']
219+
Welcome to Syncplay server, ver. 1.7.0
220+
```
221+
222+
## Build Image
83223

84-
+ `PASSWD` ：Equivalent to `--password`
224+
You can build an image directly from the source code using the following command.
85225

86-
+ `TLS=ON` ：Equivalent to `--enable-tls`
226+
```bash
227+
docker build -t syncplay https://github.com/dnomd343/syncplay-docker.git
228+
```
87229

88-
+ `ISOLATE=ON` ：Equivalent to `--isolate-room`
230+
You can also change the source code to implement your own customizations.
89231

90-
> Note that its priority is lower than command line arguments.
232+
```bash
233+
> git clone https://github.com/dnomd343/syncplay-docker.git
234+
> cd syncplay-docker/
235+
# some edit...
236+
> docker build -t syncplay .
237+
```
238+
239+
If you need images for multiple architectures, please use the `buildx` command to build.
240+
241+
```bash
242+
docker buildx build -t dnomd343/syncplay \
243+
--platform=linux/amd64,linux/386,linux/arm64,linux/arm/v7 \
244+
https://github.com/dnomd343/syncplay-docker.git --push
245+
```
91246

92-
### License
247+
## License
93248

94249
MIT ©2022 [@dnomd343](https://github.com/dnomd343)

0 commit comments

Comments
 (0)