This image combines ss-libev and simple-obfs both with the server and client included.

Tag	Description	🐳
:latest	Shadowsocks-libev & simple-obfs on alpine:latest.

docker container run [OPTIONS] nutshells/ss-obfs [COMMAND] [ARG...]

• Learn more about docker container run and its OPTIONS here;
• List all available COMMANDs: docker container run --rm --read-only nutshells/ss-obfs help
• List all ARGs (for configuring the containers):
  • For server mode: docker container run --rm --read-only nutshells/ss-obfs server --help
  • For client mode: docker container run --rm --read-only nutshells/ss-obfs client --help

Let's create a server container on the remote server:

Replace <password> with a strong password, and assign an unused port to <remote_port>.

docker container run \
       -d -p <remote_port>:12345/tcp -p <remote_port>:12345/udp \
       --name=ss-obfs-server --restart=unless-stopped --read-only \
       -e PASSWORD=<password> \
       nutshells/ss-obfs \
       server

Then run a client container on your local machine with the same configuration:

Remove 127.0.0.1: from the -p options if you want to share it with the local network.

docker container run \
       -d -p 127.0.0.1:12345:12345/tcp -p 127.0.0.1:12345:12345/udp \
       --name=ss-obfs-client --restart=unless-stopped --read-only \
       -e PASSWORD=<password> \
       -e SERVER_ADDRESS=<remote_address> -e SERVER_PORT=<remote_port> \
       nutshells/ss-obfs \
       client

See if it shows the correct IP address of your remote server.

curl -sSL https://ipinfo.io/ --socks5 127.0.0.1:12345

As you can see from the examples of the previous sections: the container accepts original command-line options of ss-libev as arguments.

Here are a few more examples:

docker container run [OPTIONS] nutshells/ss-obfs server -v [OTHER_ARG...]

docker container run --rm --read-only nutshells/ss-obfs server --help
docker container run --rm --read-only nutshells/ss-obfs client --help

However, please be informed that some of the options are managed by the entrypoint script of the container. You will encounter an error while trying to set any of them, just use the environment variables instead; as for other exceptions, just follow the message to get rid of them.

Learn to set an environment variable here, or refer to the Getting Started section for some live examples.

See the sample file.

According to the optimization tips, you'd better increase the open file limit for the container:

It's NOT recommended to enable the privileged mode to this purpose. The default limit for open files is 1024 in containers.

docker container run \
       --ulimit nofile=51200:51200 \
       [OTHER_OPTIONS] nutshells/ss-obfs server [OTHER_ARG...]

Additionally, the --net=host option provides the best network performance, use it if you know it exactly.

Get an interactive shell to a running container:

docker container exec -it <container_name> /bin/ash

You can customize the image more easily by using the --build-arg option.

Check out all the build-time arguments in this table.

Let's remove the simple-obfs plugin completely from the build:

git clone --depth 1 https://github.com/quchao/nutshells.git
docker image build -q=false --rm=true --no-cache=true \
             -t nutshells/ss-obfs \
             -f ./ss-obfs/Dockerfile \
             --build-arg WITH_OBFS=false \
             ./ss-obfs

You may want to make some modifications to the image. Pull the source code from GitHub, customize it, then build one by yourself:

git clone --depth 1 https://github.com/quchao/nutshells.git
docker image build -q=false --rm=true --no-cache=true \
             -t nutshells/ss-obfs \
             -f ./ss-obfs/Dockerfile \
             ./ss-obfs

Otherwise just pull the image from the official registry, start a container and get a shell to it, commit the changes afterwards.

docker container commit --change "Commit msg" <container_name> nutshells/ss-obfs

Follow GitHub's How-to guide for the basis.

Contributions are always welcome in many ways:

• Give a star to show your fondness;
• File an issue if you have a question or an idea;
• Fork this repo and submit a PR;
• Improve the documentation.

• Add a section about modifying kernel parameters in containers.
• Add a HealthCheck instruction.
• Add ipv6 support.

Unless specified, all codes of Project Nutshells are released under the MIT License.

Other relevant softwares:

Ware/Lib	License
Docker
Shadowsocks-libev
Simple-obfs