Docker Guide

[oc013]

Overview

The current implementation is intended to create the bare minimum environment to run the code in the repository while keeping system-level dependencies isolated to the container or its volumes. Minimal information is baked into the image itself to allow for easy updates without rebuilding it.

The Dockerfile will create an image on your system that has Nvidia drivers, CUDA and Miniconda installed. The entrypoint.sh script handles the remaining requirements of the application such as installing the conda env, downloading required model files and launching the webgui when the container is started.

2 volumes are created to cache the conda and pip dependencies and reduce needing to recreate/download them on container restarts/rebuilds.

The code from the repository is mounted in the container at /sd. Image output will be found in ./outputs on your system as expected.

A recent update adds caching all model files the script downloads into the directory ./model_cache with the filenames formatted as <filename>.<sha256sum> This allows you to symlink the directory outside of the source directory if desired and prevents needing to re-download these files if you need to re-setup the repository locally.

Requirements

• Nvidia GPU that supports CUDA 11.3+
• Docker and docker compose v2+
• nvidia-container-toolkit

Setup

git clone https://github.com/sd-webui/stable-diffusion-webui.git
cd stable-diffusion
cp .env_docker.example .env_docker
docker compose up

Initial installation will take some time, probably 10-20 mins depending on your system and internet connection.

You can stop the container with CTRL-C and restart it later by simply running docker compose up

Windows Setup

• Follow the guide to install Docker Desktop WSL 2 backend
• Verify gpu support by opening WSL and running nvidia-smi in the command line
  Make sure that your git is not converting newlines into Windows format differently from the repository

git config --global core.autocrlf input

Please comment if you got everything running successfully and any special steps needed.

Updating

docker compose down
git pull
docker compose up --build

This will only rebuild layers that have changed in the Dockerfile. Other environment changes should be handled by entrypoint.sh and then any new code for the webgui will be launched.

sd-webui  | AssertionError: Egg-link /sd/src/latent-diffusion does not match installed location of latent-diffusion (at /sd)
sd-webui  | 
sd-webui  | failed
sd-webui  | 
sd-webui  | CondaEnvException: Pip failed

This error might occur after renaming the egg info for this repository so that it does not collide with other needed dependencies.

To resolve this please run the following:

docker compose down
sudo rm -rf latent_diffusion.egg-info/
sudo rm .env_updated
docker compose up --build

Customization

There is now an .env_docker file that contains some parameters you can use to customize your setup. Generally suggest using the defaults for initial setup then you can play with the variables to your liking. For lower ram systems you might need to use one of the optimized modes to complete your setup e.g. WEBUI_ARGS=--optimized

# Force miniconda to attempt to update on every container restart
# instead only when changes are detected
CONDA_FORCE_UPDATE=false

# Validate the model files on every container restart
# (useful to set to false after you're sure the model files are already in place)
VALIDATE_MODELS=true

# Automatically relaunch the webui on crashes
WEBUI_RELAUNCH=true

# Which webui to launch
# WEBUI_SCRIPT=webui_streamlit.py
WEBUI_SCRIPT=webui.py

# Pass cli arguments to webui.py e.g:
# WEBUI_ARGS=--optimized --extra-models-cpu --gpu=1 --esrgan-gpu=1 --gfpgan-gpu=1
WEBUI_ARGS=

Troubleshooting

A helper script has been provided to clean the docker environment of the container, image and volumes. Please inspect docker-reset.sh for the relevant commands in bash if you need to recreate the steps on another OS.

[tomtom215]

Trying this on an unraid system and getting a looped error:

sd | entrypoint.sh: Launching...
sd | Relaunch count: 39
sd | Traceback (most recent call last):
sd | File "/sd/scripts/webui.py", line 3, in
sd | import cv2
sd | ModuleNotFoundError: No module named 'cv2'
sd | entrypoint.sh: Process is ending. Relaunching in 0.5s...

Which links to this script and it fails right on the setup trying to pull in the python/pip package cv2

[tomtom215]

Ok, first I want to say thank you for your patience and help (and awesome work on this project). Ultimately you were right, my setup was not being properly cleaned or reset no matter what. Finally I realised it was due to the docker-reset script failing silently and not removing the volumes and images. I just updated it, and was finally able to launch the docker container as expected!

Please see PR #1026 - Hopefully this helps others!

[oc013]

Great glad it works. Like I mentioned:

docker-reset.sh It's currently not in a good state because of the repository name change but the commands in there should show you

Also this is already resolved in dev branch #1015

[tomtom215]

Missed that mention. Apologies. I can close my PR then if this is already covered

[PreownedFIN]

Did you run this in Unraid terminal, or through the Docker webui/some other Docker manager in Unraid?
I'm also in the (very early) process of getting this to run on my Unraid box in a container. Couldn't hurt asking how you've managed. 😁

[tomtom215]

@PreownedFIN I used the unraid CLI and changed into /appdata/ and then cloned the repo and followed the steps above. I have docker compose and the nvidia plugins installed

[outlookhazy]

Instructions tested working with clean checkout

• Hardware
  • AMD Ryzen 9 5900X
  • 32.0 GB RAM
  • NVIDIA GeForce RTX 3070 8GB (driver version 516.59)
• Software
  • Windows 10 (21H2 19044.1889)
  • Docker Desktop (v4.12.0)
  • Debian WSL2 (4.4.0-19041-Microsoft)
  • sd-webui (master b9d97c9)

Test Note: I had already run into some issues with line endings on my original install, not sure exactly what I did to fix, didn't need do anything this time around but may have already had changes applied globally.

Other Notes: This is beyond the scope of this documentation, but for my normal setup I'm also using a docker-compose.override.yml file to change container network settings and run a VPN alongside the sd container for remote access. After testing, when I reapplied my override I went to rebuild/launch my normal setup (via docker-compose up --build -d) and got rpc errors from the docker registry for the cuda image.
Error in terminal was:
failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: failed to do request: Head "https://registry-1.docker.io/v2/nvidia/cuda/manifests/11.3.1-runtime-ubuntu20.04": EOF

accessing that address from a web browser, I got:
{"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":[{"Type":"repository","Class":"","Name":"nvidia/cuda","Action":"pull"}]}]}

Might be a rate limit thing? I retried a couple times over the course of a couple minutes and it eventually went through without changing anything. Not an error in the repo, just something to be aware of in case bug reports show up with that error.

Edit: oh, also I'm using WEBUI_ARGS=--no-job-manager because currently accessing from multiple browser sessions is broken when job-manager is enabled, but that's also probably outside the scope of the docker docs.

[oc013]

Awesome, thank you for verifying!

Yes docker now has a limit of 100 free pulls per 6 hours https://www.docker.com/increase-rate-limits/

[outlookhazy]

odd, I've definitely not issued 100 pulls in the last 6 hours - just got home from work..

[oc013]

Oh apparently you can't hit the registry directly without getting a token first which docker would normally handle for you automatically.

https://stackoverflow.com/questions/53494679/curl-docker-registry-authorization-error-authentication-required

The issue you're seeing must be something else.. Possible network issues somewhere along the tubes?

[outlookhazy]

That would make sense. Some HA/cache cog got stuck for a minute or two. In any case, nothing to worry about

[AndreaPi]

What about moving this guide to the Wiki, under the Installation section? This would make it more visible.

[outlookhazy]

I think that's the goal, it's here for testing/review first

[oc013]

Updated the guide with some info regarding the recent merge from dev.

Two big things to note is the models the entrypoint.sh script downloads will now be stored in a new directory called model_cache. During your first run with the new code it should redownload the models, place the models in the cache directory, then clean up the old model files that were buried inside the various directories and simply use a symlink to the cache directory.

Also added a dependency for LDSR in the environment.yaml file which was also named latent-diffusion. This repository needed to be renamed to avoid collision, so renamed it to match the organization name sd-webui If you aren't running from a fresh clone, please see my note on how to clean up the old "egg" for this repository so that the conda environment can fully update.

[chadly]

It appears the docker setup was revamped in October:

• 0725e92
• 1253394
• c4fa110

anybody have any guidance on how to run the latest within docker?

[rgzr]

There's no docker-compose.yml nor .env_docker.example on the master branch.

[chadly]

I noticed the same thing. I found this arktronic/sd-multi repo which includes a very nice docker setup for running this project (along with some others).