mirror of
https://github.com/shadowsocks/shadowsocks-libev.git
synced 2026-10-15 08:33:56 +00:00
Max Lv
bff687bd34
Document the shadowsocks-libev history and shadowsocks-c rename, and recommend Docker installation with mounted configuration and TCP/UDP port mappings. Add native AMD64/ARM64 builds of the unprivileged static runtime image, real container relay and shutdown tests, and GHCR publication after both architecture checks pass. All 24 build/test checks pass at reviewed head 3f3f6bf8e01e5614821d1e15fda3ad8f07812902; publication is intentionally skipped on pull requests.
83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# Docker image and static Linux builds
|
|
|
|
Use `ghcr.io/shadowsocks/shadowsocks-c` for Linux AMD64 or ARM64. The
|
|
[README quick start](../../README.md#docker-recommended) shows server configuration,
|
|
TCP/UDP port mapping and a read-only configuration mount. Docker Desktop runs
|
|
these Linux images on macOS and Windows.
|
|
|
|
The default entrypoint is `ss-server -c /etc/shadowsocks-c/config.json`.
|
|
Passing arguments overrides that default configuration argument. The image runs
|
|
as UID/GID `65532:65532` unless `--user` is supplied; the mounted file must be
|
|
readable by that user. Logs go to standard output/error. No writable filesystem
|
|
is required for normal server operation.
|
|
|
|
To update a running server, pull the desired tag, remove the old container with
|
|
`docker rm -f shadowsocks-c`, and repeat the quick-start run command. The host
|
|
configuration file is preserved. `latest` tracks `master`; choose a published
|
|
version tag or `sha-<full-commit>` to pin a build.
|
|
|
|
For a SOCKS5 client, override the entrypoint with
|
|
`--entrypoint /usr/local/bin/ss-local`, supply a client configuration using `-c`,
|
|
and publish the configured local TCP/UDP port. Bind the local listener to
|
|
`0.0.0.0` inside the container and restrict its host mapping to loopback, such as
|
|
`-p 127.0.0.1:1080:1080/tcp -p 127.0.0.1:1080:1080/udp`.
|
|
|
|
## Publishing
|
|
|
|
`.github/workflows/docker.yml` builds each architecture on a native runner and
|
|
exercises the actual scratch server/client containers with concurrent TCP,
|
|
hostname resolution, UDP and clean shutdown. PRs run these checks without
|
|
publishing. Pushes to `master` publish `latest` and `sha-<full-commit>`; `v*`
|
|
version tags publish the version without the leading `v` and the commit tag.
|
|
The multi-platform tag is assembled only after both architecture tests pass.
|
|
Publishing uses the repository's `GITHUB_TOKEN` with `packages: write`.
|
|
|
|
The first image becomes available after this workflow lands on `master` and
|
|
completes. GitHub initially creates packages as private: a package administrator
|
|
must set `shadowsocks-c` to **Public** in its package settings before anonymous
|
|
pulls work. This is a one-time registry setting; see
|
|
[GitHub's container registry documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images).
|
|
Until then, the quick start also provides a local image build command.
|
|
|
|
## Build locally
|
|
|
|
The Alpine/musl builder uses Clang with LLD by default and links both third-party dependencies and libc statically.
|
|
`WITH_STATIC=ON` alone only selects static third-party libraries; this image also
|
|
passes `-DCMAKE_EXE_LINKER_FLAGS=-static` and omits shared-library outputs.
|
|
The compile, unit/vendor tests and six-method TCP/UDP relay tests run with Docker
|
|
network access disabled. The final ELF check rejects interpreters and dynamic
|
|
library dependencies. Initial image/toolchain installation requires networking.
|
|
|
|
From the repository root, export binaries and licenses (ARM64 example):
|
|
|
|
```sh
|
|
docker build --platform linux/arm64 -f docker/static/Dockerfile \
|
|
--target artifacts --output type=local,dest=build-artifacts/static-linux-arm64 .
|
|
```
|
|
|
|
Requires Docker Buildx/BuildKit. If Docker Hub is unavailable, add
|
|
`--build-arg ALPINE_IMAGE=public.ecr.aws/docker/library/alpine:3.24`.
|
|
An alternate package mirror can be selected with `--build-arg ALPINE_MIRROR=https://mirrors.aliyun.com/alpine`; APK signature checks remain enabled.
|
|
Docker build proxy settings apply to package installation; a broken configured
|
|
proxy can be bypassed for this command with empty `HTTP_PROXY`, `HTTPS_PROXY`,
|
|
`ALL_PROXY` build arguments and their lowercase equivalents.
|
|
|
|
Use `--platform linux/amd64` and a different destination for x86-64. Docker needs
|
|
a matching native builder or CPU emulation to compile and run the tests for a
|
|
foreign architecture. Add `--build-arg SS_MINIMAL=ON` for the minimal profile.
|
|
|
|
Build the scratch runtime image using the same cached build stage:
|
|
|
|
```sh
|
|
docker build --platform linux/arm64 -f docker/static/Dockerfile \
|
|
--target runtime -t shadowsocks-c:static-arm64 .
|
|
docker run --rm -p 8388:8388/tcp -p 8388:8388/udp \
|
|
shadowsocks-c:static-arm64 \
|
|
-s 0.0.0.0 -p 8388 -k example-password -m aes-256-gcm -u
|
|
```
|
|
|
|
The runtime image has no shell or external plugin executables. Supply any SIP003
|
|
plugin and its own runtime requirements separately. Configuration files can be
|
|
bind-mounted and passed with `-c`. Exported binaries run on Linux with the same
|
|
CPU architecture; they do not run directly on macOS or Windows.
|