mydigitalwalk/sheepit-docker repository overview

⁠A simple dockerized SheepIt render farm client running as Normal user

Fork of @agsphoenix and @dapor2000's client. It's small, and runs the client as a normal user (for extra security). You can set the number of cpus and memory for the client, and any other option supported by the client. It also provides a healthcheck built in.

Features

• Auto downloads updated client only when needed
• Runs as a user for added security
• Built in Healthcheck

⁠Versions

The current latest tag uses Debian Buster (buster) with JRE 11. There is also a stretch tag that uses the previous Debian release, with an older version of java.

I hope to make one that will use Alpine.

⁠Instructions

To run it, use your username and password (or the key that you got from your sheepit profile). If you were to do a docker run, it would look like

docker run -d --name "sheepit" -e user_name=XXXXXX \
        -e user_password=XXXXXX -h "$(hostname)" \
        mydigitalwalk/sheepit-docker:latest

It's suggested that you use a key instead of your Sheepit password. Go to your account page⁠ to create your key. Use it as your user_password.

Setting the hostname lets you see how the host is doing on the Sheepit website dashboard. Otherwise each time it runs it will get a random name.

⁠Options

The Sheepit client options are passed by Environment variables: cpu, memory, and options.

• cpu=4: Sheepit will use this many cpus. Set to 0 to use all. Must be a integer.
• memory=8000: Memory (in MB). Can also specify M, G, etc.
• options: All other options, such as options="-priority=19 -gpu=CUDA_0 -compute-method GPU"

To see all the client options, run:

docker run --rm -e options="--help" mydigitalwalk/sheepit-docker:latest

⁠Docker Compose

Here are some docker-compose.yml examples.

⁠Basic Without Volumes

version: '2.2'
services:
  app:
    hostname: Your Host Name (Whatever you want)
    image: mydigitalwalk/sheepit-docker:latest
    restart: always
    cpus: 2
    cpu_shares: 100
    mem_limit: 4000M
    environment:
      - user_name=Your User Name
      - user_password=Your Pass Phrase
      - cpu=2
      - options=-priority 19

⁠With a Volume and an .env file

In .env, set your variables.

# Sheepit Username and Password / Key
user_name=
user_password=

# The name here will identify it on Sheepit's dashboard.
hostname=

# Docker cpu limit. Can be a decimal. Set to 0 to use all cpus.
cpu_docker_limit=3.5

# Sheepit will use this many cpus (integer only). Set to 0 to use all cpus.
cpu=4

# Memory Limit (M, G, T, P)
memory=3200M

# Other options passed to Sheepit
options=-priority 19

# TimeZone (optional). Defaults to UTC.
# TZ=Your Time Zone

In docker-compose.yml (This shouldn't need to be modified)

version: '2.2'
services:

  app:
    hostname: ${hostname}
    image: mydigitalwalk/sheepit-docker:latest
    restart: always
    cpus: ${cpu_docker_limit}
    mem_limit: ${memory}
    cpu_shares: 100
    env_file:
      - .env
    volumes:
      - cache:/sheep/cache

volumes:
  cache:

⁠Healthcheck

A health check runs every 5 mins to avoid situations where the render locks up for days before being noticed. It checks two items:

1. Makes sure that Sheepit is up and running.

2. That Sheepit is Rendering, Downloading, or "No job available" (on hold from the server), using the output of the application. These have to happen within interval * retries minutes. By default the total timeout is 60 minutes, which should be long enough it won't reboot if the server doesn't have a job or is overloaded, which can last up to 30 mins or more. And it shouldn't be too long if there is an issue.

To override the defaults in docker-compose.yml.

healthcheck:
  test: /healthcheck.sh
  interval: 300s
  timeout: 300s
  retries: 12

To disable it in docker-compose.yml

  healthcheck: none

Or to disable it in docker run:

--health-cmd none

The reason I chose 5 mins is from my tests the client sometimes won't any output for a few minutes. I found 5 mins to give a good log of the health of the application.

As you probably know, docker does not auto-restart unhealthy containers. This requires swarm, autoheal, or some other system taking care of the container when it's in an unhealthy state.

⁠Volumes

The client can download a lot of data. Much of it can be reused. If you want to save on bandwidth, use a volume.

-v volume_name:/sheep/cache

-v /path/to/your/saved/cache_data:/sheep/cache

You may have to do your own housecleaning. The client does a pretty good job of not keeping old data, but if you're using docker-compose, once a month you can run this which will remove the volume and restart the container.

docker-compose down -v      # deletes the volume
docker-compose up -d

If you use your own data location, it will need to be writable by the sheepit user (23847). While the app will change the /sheep/cache directory to be owned by the sheepit user, it does not decend the directory tree. If you have existing data to be used by Sheepit, set the owner of the folders and files:

chown 23847 -R /path/to/your/saved/cache_data

⁠Timezone

By default the time zone for the container is UTC. The Sheepit client program has optionsto do some things at specific times (for example, the option --request-time). To make it easier to specify the specific times, set the container's timezone with TZ=America/Denver

⁠Troubleshooting

⁠Dependency Error

If you see an error "Error Renderer has generated no output file, possibly a wrong project configuration or you are missing required libraries. Will try another project in a few minutes.", this usually happens when the render program has run out of memory and thus has not produce any output. You can ignore it and it will try another blend.

⁠Login as root

The container runs everything as a normal user, even shell logins. If you need a root shell in the running container:

docker exec -it -u root -w / sheepit bash