stilleshan/frpc: install scripts and a Docker image for the frp client

Packaging, not a tunnel implementation

The project description makes the scope clear. This is a set of one-click install and uninstall scripts and a Docker image for the frp intranet penetration client frpc, based on the original frp project at github.com/fatedier/frp, and it supports installation and deployment on Synology NAS, Linux servers and Docker.

That framing matters, because frp itself is a separate and well-known project, and the two things this repository adds are operational rather than functional. The scripts download the upstream release, place the binary and the configuration in a known location, and register a service. The image does the same thing in a container.

The value of that layer is real, and it is aimed at a particular audience. A Synology NAS is a Linux box with an unusual package manager and no assumption that you will log in as root, and a user who wants to expose a home service to the internet through a frp server would otherwise be writing a systemd unit and a download script by hand. The repository's update history shows it being maintained as that layer over time, with the configuration format changing to toml in March 2024 and ARM support added to the script and the image in May 2021.

It is worth being clear about what you are taking on. The client is upstream frp's, the frp server is not here, and the version in the image is not the latest one.

The Docker image, and the base it builds on

The Dockerfile is short, and one line in it is worth reading closely. The image is built on alpine:3.8, the maintainer is Stille, the frp version is pinned with an environment variable at 0.70.0, and the timezone is set to Asia/Shanghai with the usual symlink dance for tzdata.

The platform detection is the interesting part, because the image supports both x86 and ARM:

RUN if [ "$(uname -m)" = "x86_64" ]; then export PLATFORM=amd64 ; \
 	elif [ "$(uname -m)" = "aarch64" ]; then export PLATFORM=arm64 ; \
 	elif [ "$(uname -m)" = "armv7" ]; then export PLATFORM=arm ; \
 	elif [ "$(uname -m)" = "armv7l" ]; then export PLATFORM=arm ; \
 	elif [ "$(uname -m)" = "armhf" ]; then export PLATFORM=arm ; fi \

It then downloads the matching upstream release archive with wget, unpacks it, and moves the frpc binary and the frpc.toml configuration into /frp. The volume is declared as /frp and the command is /frp/frpc -c /frp/frpc.toml, so the configuration is a mounted file rather than something baked into the image.

The fact that the base is alpine 3.8 is worth flagging, because that is an old release line, and it is combined with a wget invocation that uses --no-check-certificate. Neither is a fatal problem for a small tunnel client, but both are the kind of detail that a security review will ask about, and they are visible in the file rather than hidden.

The one-click script, and the service it registers

The Linux server route is the one the README documents in full. The install is a single line that downloads the script, makes it executable and runs it:

wget https://raw.githubusercontent.com/stilleshan/frpc/master/frpc_linux_install.sh && chmod +x frpc_linux_install.sh && ./frpc_linux_install.sh

and the uninstall is the same shape with the uninstall script. The configuration lives at /usr/local/frp/frpc.toml, and after editing it you restart the service:

vi /usr/local/frp/frpc.toml
# 修改 frpc.toml 配置
sudo systemctl restart frpc

The repository contains that service definition, frpc.service, alongside the two Linux scripts and the two Synology ones, frpc_synology_install.sh and frpc_synology_uninstall.sh, and a frpc.toml at the root that the container image ships.

The pattern is the familiar one for a small systemd deployment. A single binary, a single configuration file, a service that can be restarted, and an uninstall script that removes what the install script added. What the script does beyond that is not described in the README, so a reader who wants to know exactly what runs on their machine should read the script, which is the whole point of a packaging repository that keeps the scripts in the tree rather than only in a release archive.

Four routes, and the order the README recommends them in

The usage section presents four deployment methods and tells the reader to pick according to the situation.

The first is Docker on a Synology NAS, marked as the preferred option for Synology models that support Docker, with a tutorial link. The second is the one-click script on a Synology NAS, for the models that do not support Docker, also with a tutorial. The third is the one-click script on a Linux server, for an internal Linux server or a virtual machine, and the script supports both x86 and ARM. The fourth is Docker on a Linux server, for the same internal server or virtual machine case.

The distinction that matters is Docker support on the NAS, and the update history explains why the script route still exists. The notes record that from 0.36.2 the Docker image supports x86 and ARM, that the Linux script was updated to support x86 and ARM at the same time, and that an x86 Synology running DMS 7.0 can use the Linux version of the script directly, with the note that there was no ARM version to try and readers should attempt it themselves.

That is an honest statement of what had been tested and what had not, and it is a good model for the rest of the documentation, which links three tutorials covering Docker on a NAS, the free frp tutorial for a NAS without Docker, and a beginner's guide to configuring frpc.toml.

The configuration file, and the restart discipline

The Docker section opens with the warning that matters most in practice. To avoid the container failing to start and restart-looping because of a mount, format or configuration error in frpc.toml, you must make sure the file is configured correctly before you run the start command.

The reasoning is straightforward once you see the volume. The container declares /frp as a volume and starts with /frp/frpc -c /frp/frpc.toml, so your file is mounted directly over the one the image ships. A malformed file is therefore not a startup error the container can report, it is an immediate exit, and with --restart=always that becomes a loop.

The documented workflow avoids the problem by putting the file in place first. You clone the repository, which brings the sample frpc.toml with it, you edit it at /root/frpc/frpc.toml, and then you start the container:

docker run -d --name=frpc --restart=always -v /root/frpc/frpc.toml:/frp/frpc.toml stilleshan/frpc

The mounted path in that command assumes the clone, and the README says so, and that you can instead create the file anywhere and change the path. And the last piece is the same discipline as the script route: a configuration change needs a restart, here docker restart frpc, and the README shows editing /root/frp/frpc.toml and restarting the container.

The mirror, and what to think about before running the script

Every download in the README has a second form, and the reason is stated in the update history as an update to the domestic mirror for easier use. The install line becomes:

wget https://ghfast.top/https://raw.githubusercontent.com/stilleshan/frpc/master/frpc_linux_install.sh && chmod +x frpc_linux_install.sh && ./frpc_linux_install.sh

The same pattern applies to the uninstall script and to the git clone in the Docker route, where the mirror is used for the repository itself.

The mirror exists because a raw GitHub URL is slow or unreachable from some networks, and for a user in that situation it is a real convenience. It is also, structurally, a third party in the path of a script that is then executed as root, and the wget that fetches the frp release in the Dockerfile uses --no-check-certificate besides.

None of that makes the repository a bad choice for its audience, and the audience is people who want a tunnel working on a NAS tonight. But an organisation with a policy about executing remote scripts should read the install script first, and should consider the Docker route with a pinned digest and a configuration they wrote themselves, since the container does not need the script at all.

The project also publishes a Docker registry of its own, docker.ioiox.com, alongside the Docker Hub image, and the upstream frp project is linked from the README for anyone who needs the server side or the current client.

Where this repository is the wrong choice

The first wrong-tool case is a deployment that needs a current frp. The image pins frp 0.70.0, and the README's own update history records that the configuration format moved to toml in March 2024, which means the shipped image is behind the current upstream on both the binary and the configuration format. A deployment that needs recent upstream features, or that has been migrated to the toml format in its own configuration, should build the image from a current release rather than use this one.

The second is a server-side or production deployment with a change process. The scripts are designed to be run and to write into system directories, and the Docker image is a single-purpose container with a mounted configuration file. A team that deploys through configuration management, with immutable images and secrets pulled from a vault, gains very little from a script that curls a file and runs it as root.

The third is a user who wants a managed tunnel. This is a client for a self-hosted frp server, and you still need the server, a domain, and whatever the server operator requires.

The fourth is a security-sensitive environment where a wget with --no-check-certificate and a script executed as root are not acceptable processes. In that case, the sensible use of this repository is as a reference for the layout, the service unit and the container shape, and then build your own image with the checks you require.

Editorial conclusion

Adopt this repository if you run frpc on a Synology NAS or a small Linux server and want the install, the systemd service and the container image handled for you rather than assembling the upstream tarball by hand. Do not adopt it if you need current frp features, because the image is pinned to frp 0.70.0 and the configuration format moved to toml in a later update, and do not treat it as a hardened deployment, since the scripts download and execute a remote script over a plain wget. Before you deploy, read the frpc.toml that the image ships and replace it with your own, because the container mounts your file over it, and check the service definition so that the restart behaviour matches how you want the tunnel to come back.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. stilleshan/frpc on GitHub