Skip to content

README.md

Latest commit

 

History

History
82 lines (66 loc) · 4.44 KB

README.md

File metadata and controls

82 lines (66 loc) · 4.44 KB
Raw

Docker image and static Linux builds

Use ghcr.io/shadowsocks/shadowsocks-c for Linux AMD64 or ARM64. The README quick start 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. 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):

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:

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.