Using one command to start the [Syncplay](https://syncplay.pl/) service. Yes, it's very simple.
Using one command to start the [Syncplay](https://syncplay.pl/) service. Yes, that's it.
```bash
```bash
> docker run --rm --net=host dnomd343/syncplay
$ docker run --rm --net=host dnomd343/syncplay
Welcome to Syncplay server, ver. 1.7.1
Welcome to Syncplay server, ver. 1.7.4
```
```
> Pressing `Ctrl+C` will exit the service.
> Pressing `Ctrl+C` will exit the service.
<details>
<summary><b>Unable to access Docker Hub?</b></summary>
<br/>
If you cannot access the Internet, you need to obtain the OCI image and copy it into storage medium. For details, see [offline usage](#Registry).
If you are located in China Mainland that cannot access the Docker Hub normally, you can replace the `dnomd343/syncplay` as `ccr.ccs.tencentyun.com/dnomd343/syncplay` , which will access the TCR service at Guangzhou.
</details>
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.
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.
In order to run the service better, we can use the following command to make Syncplay run in the background and keep it started.
In order to run the service better, we can use the following command to make Syncplay running in the background.
```bash
```bash
docker run -d --net=host --restart=always --name=syncplay dnomd343/syncplay
The server will be restarted when necessary, or the Docker service 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.
Sometimes we need to restart the server, 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.
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 options in it, Syncplay will automatically read it when it starts, avoiding the need to type a large number of arguments in the command line.
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 options in it, Syncplay will automatically read it when it starts, avoiding the need to type a large number of arguments in the command line.
@ -52,31 +66,31 @@ motd: |
More information...
More information...
```
```
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.
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 private key and certificate file.
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.
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 certificate file, and Syncplay requires you to provide the following three files.
+ `cert.pem`：The certificate issued by the CA.
+ `cert.pem`: The certificate issued by the CA.
+ `chain.pem`：The certificate chain of CA service.
+ `chain.pem`: The certificate chain of CA service.
+ `privkey.pem`：The private key for the certificate.
+ `privkey.pem`: The private key of the certificate.
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.
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.
```bash
```bash
acme.sh --install-cert -d 343.re \
$ acme.sh --install-cert -d 343.re \
--cert-file /etc/ssl/certs/343.re/cert.pem \
--cert-file /etc/ssl/certs/343.re/cert.pem \
--ca-file /etc/ssl/certs/343.re/chain.pem \
--ca-file /etc/ssl/certs/343.re/chain.pem \
--key-file /etc/ssl/certs/343.re/privkey.pem
--key-file /etc/ssl/certs/343.re/privkey.pem
```
```
Now that we are ready, we just need to execute the following command and a more secure and private Syncplay service will be started.
Now that we are ready, we just need to execute the following command and a more secure and private Syncplay service will be started.
> Note that the client's server address must match the certificate, otherwise the connection will fail.
> Note that the client's server address must match the certificate, otherwise the connection will fail.
@ -89,80 +103,112 @@ You can customize the Syncplay server by specifying the following command line a
> 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.
> 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.
+ `--port [PORT]` ：Listening port of Syncplay server, the default is `8999` .
+ `--config [FILE]` : Specify the configuration file, the default is `config.yml` .
+ `--password [PASSWD]` ：Authentication when the user connects to the syncplay server, not enabled by default.
+ `--port [PORT]` : Listening port of Syncplay service, the default is `8999`.
+ `--motd [MESSAGE]` ：The welcome text after the user enters the room, not enabled by default.
+ `--password [PASSWD]` : Authentication when connecting to the server, not enabled by default.
+ `--salt [TEXT]` ：A string used to secure passwords (e.g. Rainbow-tables), defaults to empty.
+ `--motd [MESSAGE]` : The welcome text after the user enters the room, not enabled by default.
+ `--random-salt` ：Use a randomly generated salt value, valid when `--salt` is not specified, not enabled by default.
+ `--salt [TEXT]` : Specify a random string as the [salt value](https://en.wikipedia.org/wiki/Salt_(cryptography)) used to secure password, defaults to empty.
+ `--isolate-rooms` ：Room isolation enabled, users will not be able to see information from anyone other than their own room, not enabled by default.
+ `--random-salt` : Using randomly generated salt value, valid when `--salt` is not specified, not enabled by default.
+ `--disable-chat` ：Disables the chat feature, not enabled by default.
+ `--isolate-rooms` : Enable room isolation, users cannot see information from anyone outside their room, not enabled by default.
+ `--disable-ready` ：Disables the readiness indicator feature, not enabled by default.
+ `--disable-chat` : Disable the chat feature, not enabled by default.
+ `--enable-stats` ：Enable the server statistics feature, the data will be saved in the `stats.db` file, not enabled by default.
+ `--disable-ready` : Disable the readiness indicator feature, not enabled by default.
+ `--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.
+ `--enable-stats` : Enable the server statistics feature, the data will be saved in the `stats.db` file, not enabled by default.
+ `--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.
+ `--enable-tls` : Enable TLS support, the files need to be mounted in the `/certs/` directory, including `cert.pem` , `chain.pem` and `privkey.pem`, not enabled by default.
+ `--max-username [NUM]` ：Maximum length of usernames, default is `150`.
+ `--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.
+ `--max-chat-message [NUM]` ：Maximum length of chat messages, default is `150` .
+ `--max-username [NUM]` : Maximum length of usernames, default is `16` .
+ `--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.
+ `--max-chat-message [NUM]` : Maximum length of chat messages, default is `150`.
+ `--listen-ipv4 [ADDR]` ：Customize the listening address of the Syncplay service on the IPv4 network, not enabled by default.
+ `--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.
+ `--listen-ipv6 [ADDR]` ：Customize the listening address of the Syncplay service on the IPv6 network, not enabled by default.
+ `--listen-ipv4 [ADDR]` : Listening address of Syncplay service on IPv4 network, not enabled by default.
> Only when you specify `--listen-ipv4`, Syncplay will not listen on IPv6 and vice versa. When both are specified, Syncplay will work under dual-stack networking.
+ `--listen-ipv6 [ADDR]` : Listening address of Syncplay service on IPv6 network, not enabled by default.
> When you specify only `--listen-ipv4` , Syncplay will not listen on IPv6 and vice versa. When both are specified, Syncplay will work under dual-stack networking.
Add `--version` option to print Syncplay and Python versions, as well as CPU architecture.
-p PORT, --port PORT listen port of syncplay server
-v, --version Show version information and exit.
--password PASSWD authentication of syncplay server
-c FILE, --config FILE
--motd MESSAGE welcome text after the user enters the room
Specify the configuration file path, the default is
--salt TEXT string used to secure passwords
`config.yml`.
--random-salt use a randomly generated salt value
-p PORT, --port PORT Listening port of Syncplay service, the default is
--isolate-rooms room isolation enabled
8999.
--disable-chat disables the chat feature
-k PASSWD, --password PASSWD
--disable-ready disables the readiness indicator feature
Authentication when connecting to the server.
--enable-stats enable syncplay server statistics
-m MESSAGE, --motd MESSAGE
--enable-tls enable tls support of syncplay server
The welcome text after the user enters the room.
--persistent enables room persistence
--salt TEXT A string used to secure passwords, defaults to empty.
--max-username NUM maximum length of usernames
--random-salt Use a randomly generated salt value, valid when
`--salt` is not specified.
--isolate-rooms Enable room isolation, users cannot see information
from anyone outside their room.
--disable-chat Disables the chat feature.
--disable-ready Disables the readiness indicator feature.
--enable-stats Enable the server statistics feature, the data will be
saved in the `stats.db` file.
--enable-tls Enable TLS support, the private key and certificate
needs to be mounted in the `/certs/` directory.
--persistent Enable room data persistence, the information will be
saved to the `rooms.db` file, only valid when
`--isolate-rooms` is not specified.
--max-username NUM Maximum length of usernames, default is 16.
--max-chat-message NUM
--max-chat-message NUM
maximum length of chat messages
Maximum length of chat messages, default is 150.
--permanent-rooms [ROOM ...]
--permanent-rooms [ROOM ...]
permanent rooms of syncplay server
Specifies a list of rooms that will still be listed
--listen-ipv4 INTERFACE
even if their playlist is empty, only valid when
listening address of ipv4
`--persistent` is specified, defaults to empty.
--listen-ipv6 INTERFACE
--listen-ipv4 ADDR Listening address of Syncplay service on IPv4.
listening address of ipv6
--listen-ipv6 ADDR Listening address of Syncplay service on IPv6.
```
```
</details>
## Configure File
## Configure File
If you configure a lot of options, it will be quite troublesome and error-prone to enter a large number of command line arguments 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 arguments in the command line. Syncplay will automatically read and load it when starting, but it should be noted that if the same arguments are specified on the command line, will override the configuration file's options.
If you configure a lot of options, it will be quite troublesome and error-prone to enter a large number of command line arguments every time you start. At this time, you can write them into the configuration file.
Creating `config.yml` file in the working directory, it uses YAML format and supports all arguments in the command line. Syncplay will automatically read and load it when starting, but it should be noted that if the same arguments are specified on the command line, will override the configuration file's options.
```yaml
```yaml
port: 7999
port: 7999
@ -188,25 +234,28 @@ motd: |
More information...
More information...
```
```
You can also use JSON or TOML formats, relying on the suffix to identify them. The default file name `config.yml` can be obtained by adding the `--config` parameter or passing the `CONFIG` environment variable.
## Environment Variables
## Environment Variables
The Syncplay container also supports configuration through environment variables. It supports three types of fields: numbers, strings, and boolean, this means that `permanent-rooms` is not supported. Environment variables are named in uppercase letters, and `-` is replaced by `_` , boolean values are represented by `ON` or `TRUE`. The following is an example of using environment variables.
The Syncplay container also supports configuration through environment variables. It supports three types of fields: numbers, strings, and boolean, this means that `permanent-rooms` is not supported. Environment variables are named in uppercase letters, and `-` is replaced by `_` , boolean values are represented by `ON` or `TRUE`. The following is an example of using environment variables.
```bash
```bash
docker run -d --net=host --restart=always --name=syncplay \
You may have noticed that we support three configuration methods: command line arguments, configuration file and environment variables. Their priority is from high to low, that is, the command line arguments will override the options of the configuration file, and the configuration file will override the environment variables. You can use them together.
You may have noticed that we support three configuration methods: command line arguments, configuration file and environment variables. Their priority is from high to low, that is, the command line arguments will override the options of the configuration file, and the configuration file will override the environment variables. You can use them together.
## Docker Compose
## Docker Compose
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.
Using `dockercompose` to deploy Syncplay is a more elegant way. You need to create a `docker-compose.yml` configuration file and write the following example.
```yaml
```yaml
# /etc/syncplay/docker-compose.yml
# /etc/syncplay/docker-compose.yml
version: '3'
services:
services:
syncplay:
syncplay:
container_name: syncplay
container_name: syncplay
@ -220,69 +269,128 @@ services:
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.
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.
```bash
```bash
> docker-compose up
$ docker compose up -d
Recreating syncplay ... done
[+] Running 1/1
Attaching to syncplay
✔ Container syncplay Started
syncplay | Welcome to Syncplay server, ver. 1.7.1
```
```
> Adding the `-d` option allows the service to run in the background.
> Adding the `-d` option allows the service to run in the background.
Similarly, you can map the certificate directory to enable TLS functionality, and edit the `config.yml` file to configure more options.
Similarly, you can map the certificate directory to enable TLS functionality, and edit the `config.yml` file to configure more options.
## Security
In the above commands, we use `--net=host` to expose external services, which means that the container can directly access the host network. From a security perspective, it is recommended to use the bridge network to map the `tcp/8999` port, although it may result in a slight performance loss.
By default, Docker runs containers as the root user, which can pose a security risk. The images built by this project complies with the OCI standard, so [Podman](https://podman.io/) can be used completely instead of Docker, which runs in non-root mode by default.
Of course, we can also use Docker [rootless mode](https://docs.docker.com/engine/security/rootless/), but it is quite cumbersome to configure. If you only want to use Docker, you can specify the `UID` and `GID` when building the image, and the container will not have root permissions.
```bash
# You can view the current non-root UID and GID value.
$ id
uid=1000(dnomd343) gid=1000(dnomd343) ...
# Use the obtained UID and GID values as build arguments.
$ docker build -t my-syncplay \
--build-arg USER_UID=1000 \
--build-arg USER_GID=1000 \
https://github.com/dnomd343/syncplay-docker.git
$ docker run -d -p 8999:8999 \
--restart=always --name=syncplay my-syncplay
```
## Registry
The images released by this project comply with the [OCI Image Format Specification](https://github.com/opencontainers/image-spec) and can be distributed on any registry that complies with the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). In the current workflow, Github Action will be automatically distribute the same images to the following registries:
There are four CPU architectures supported, namely `amd64` , `arm64` , `i386` and `arm/v7` . When pulling the image, the container tool will automatically select the appropriate image based on the host architecture.
You can pull the original OCI image and store it as tar file, which can be used offline. It is recommended to use the [skopeo](https://github.com/containers/skopeo) tool to achieve this.
> You can use the `docker save` command to export, but only supports a single architecture.
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` .
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` .
```bash
```bash
> docker run --rm --env DEBUG=ON dnomd343/syncplay
$ docker run --rm --env DEBUG=ON dnomd343/syncplay
For some reason, you may need to change the path of the configuration files or working directory. This is possible in the Syncplay container, which requires you to specify it using environment variables.
For some reason, you may need to change the path of the configuration files or working directory. This is possible in the Syncplay container, which requires you to specify it using environment variables.
+ `TEMP_DIR` ：Temporary directory, it does not need to be persisted, defaults to `/tmp/`
+ `TEMP_DIR` ：Temporary directory, it does not need to be persisted, defaults to `/tmp/` .
+ `WORK_DIR` ：The working directory, which stores data related to Syncplay, defaults to `/data/`
+ `WORK_DIR` ：The working directory, which stores data related to Syncplay, defaults to `/data/` .
+ `CERT_DIR` ：Certificate directory, which is used to store TLS certificates and private key files, defaults to `/certs/`
+ `CERT_DIR` ：Certificate directory, which is used to store TLS certificates and private key files, defaults to `/certs/` .
+ `CONFIG` ：Configuration file, which defines the YAML configuration read by the bootstrap script, defaults to `config.yml`
## Build Image
## Build Image
> This project uses several [BuildKit](https://github.com/moby/buildkit) features (bundled after Docker 23.0), and other builders may have compatibility issues.
You can build an image directly from the source code using the following command.
You can build an image directly from the source code using the following command.
Dnomd343
3 months ago