Skip to content

Latest commit

 

History

History
118 lines (76 loc) · 10.2 KB

Docker.md

File metadata and controls

118 lines (76 loc) · 10.2 KB
Raw

Using SwarmUI in Docker

This document explains why and how to use SwarmUI in a Docker container. This is primarily intended for advanced users. If you've never used a Linux terminal before, this is likely too complicated for you.

Table of Contents

Why Use Docker

What is Docker? Docker is a containerization tool: That is, it lets you run software in a "restricted container" - a virtual machine inside your computer, a separation layer between where the software is running, and where everything else is running.

What is the actual practical benefit? Security, mainly. If anything unwanted happens inside your Swarm instance, it's limited to that container, and you can easily cut it off, and trust with decent confidence* that it didn't access anything outside.

*(Docker is not a guarantee, it just makes it a lot harder for malicious activity to escape. A targeted attack for example might escape through internal network access.)

Does this mean Swarm is unsafe? Well, no. Swarm is safe. ... Buuuut, Swarm does not stand up all by itself. Swarm depends on a ComfyUI backend. ComfyUI depends on python3, and a variety of python packages. You might install custom nodes from any number of third party developers. Those nodes, in turn, depend on a variety of other python packages. The risk here is referred to as a "supply chain attack": The software you're trying to use, Swarm, is safe, but a dependency of a dependency of a dependency might be maintained by some random person from Nebraska who has been thanklessly maintaining it since 2003, and that guy might have his account taken over, and malware slipped into his project. This is rare, but it has happened, and has even happened to projects depended on by Comfy & Swarm users (see for example Ultralytics breach notes here - this attack thankfully ended up damaging zero of our users, and was detected & addressed by Swarm & Comfy developers within hours, but it hurt non-Swarm-users, and the next attack might not leave us so lucky).

So doing this Docker thingy makes it safe? Well not entirely, but mostly yeah. Docker removes the majority of available attack surface, but nothing is ever a guarantee. Even with a Docker setup, always only install extensions or custom nodes from respected well known developers to minimize risk. This is also not a substitute for practicing good security in general (backup your important files externally, don't reuse passwords between sites, always use TFA, etc. -- when all is done well, even a successful hack targeting you can't do you too much harm). See also Docker's security documentation: https://docs.docker.com/engine/security/

Are there alternatives to Docker? Yes! There's plenty of containerization methods, Docker is just a well known one that Swarm has references for. If you're paranoid, you might use an entirely different machine for anything private/secure (such as accessing your bank accounts or whatever) from where you run general local software (anything like Swarm or other AI tools included). If you're on Windows and don't want to split your machine or deal with Docker, there's other "sandbox" tools such as Sandboxie that oughtta work as well.

Any bonus perks of Docker? A few. Some better control over the process, some general management perks, better assurance of privacy, the ability to destroy your instance data and remake it quickly (like a reinstall but easier, for if you're the type of person to break your install often). On Windows you may end up with slightly faster backend performance (thanks to everything just kinda running better with Linux drivers than Windows ones). On Linux it may make for a more reliable installation since Swarm will have independence from any global package installs (you don't have to worry about your global python install if Swarm has a container with its own python install).

Options

Standard Contained Installation

The standard contained installation will precompile Swarm in the build stage, and create independent persistent volumes for Data and dlbackend, as well as forwarding Models and Output folders directly.

This makes it easy to run multiple instances from one Swarm install, but is a bit more annoying for if you need to directly access the underlying files.

Open Passthrough Installation

The "open passthrough" container installation will simply run Swarm in-place, but as a container. This is a bit less rigid and proper, but may be more convenient for personal usage.

It should still be relatively secure, but a targeted attack could mess with things (eg alter the docker files to cause a problem on next launch).

You probably shouldn't do a passthrough of a pre-existing install unless you know what you're doing, as the python environment is likely to be corrupted - the container and the host cannot share control of a python env folder without something going haywire.

Be aware that the permissions on files may be weird, as the container will treat files as owned by root, so if you want to access them from host you'll have to use sudo chown yournamehere:yournamehere -R ./ first (won't break anything in the container).

Open Passthrough is very much not recommended on Windows, the Linux+Windows interaction in a folder will lead to weird results, use at your own risk.

Customizing

If you have more specific needs, such as alternate folders to forward (eg if you have models on a different drive) or forward alternate ports or etc, you can simply copy the launch-standard-docker.sh or launch-open-docker.sh file, name your copy custom-launch-docker.sh, and put whatever modifications you want inside (do not edit the original script, to avoid git conflicts). Then, of course, simply use your edited copy.

You shouldn't need to edit the Dockerfiles, the difference between Standard vs Open is just Standard copies in source files, and Open does not, so pick whichever of the two makes more sense for your situation.

You can mount a models directory with :ro on the end to make it readonly. Just be sure to disable "Model Metadata Per Folder" in server configuration if you mount a Models folder this way, and understand that "Edit Metadata" won't work if you do this.

Which To Pick

If in doubt, go with Standard, that's why it's named that. But if Open sounds right for you, go for it. Or, if you know what you're doing with Docker and want to maximize security and control, make your own docker container. The docker files include here should serve as great starting point examples.

How To

The steps are similar for all OS's, with different setup requirements.

In all cases you don't need to be an expert, but will need a bit of familiarity with basic operation of a command line interface. Unfortunately Docker is not quite "plug-n-play", but it's getting close.

Linux

Windows

  • Install Docker Desktop for Windows: https://docs.docker.com/desktop/setup/install/windows-install/
    • Be warned this has a lot of prerequisites, including BIOS settings and Windows WSL2 activation. Be prepared for a long and annoying process if you've never done this before. Sorry.
    • It's also pretty buggy from my own testing. (Maybe a Docker expert can help improve this?)
  • Install git from https://git-scm.com/download/win
  • open a terminal to the folder you want swarm in and run git clone https://github.com/mcmonkeyprojects/SwarmUI
  • Open the launchtools folder and doubleclick either windows-standard-docker.bat or windows-open-docker.bat
  • Open a browser to http://localhost:7801

Mac

Mac information is currently untested, but presumed to work fairly similar to Linux as long as you get Docker installed on your Mac per Docker's documentation.

Docker-Compose

If you're a "docker compose" fan, there is an included docker compose file you can use as usual, which is equivalent to the "standard" option above.

If you're not an active "docker compose" fan that needs it for some reason, I do not recommend it.

Advanced Usage, Notes, Troubleshooting

  • If you need to access a shell inside the Docker container while it's running, use docker exec -it swarmui bash -l
  • The "Standard" docker shoves everything in the / file root for legacy reasons, the "Open" docker puts things inside /SwarmUI
  • If you have an AMD or Intel GPU... uh, there's probably appropriate tooling for that. No idea what it is, good luck. (If you have such a GPU and find the answers to that, please PR docs about it!)