From b672cc37a7e6d9e1cdf4a9b0175bd8342fd1d34f Mon Sep 17 00:00:00 2001 From: Eugene Brodsky Date: Mon, 24 Jun 2024 16:51:06 -0400 Subject: [PATCH] docs: overhaul Docker documentation, add to main README --- README.md | 29 ++++++++++ docker/README.md | 70 ++++++++++++++++++------- docs/installation/040_INSTALL_DOCKER.md | 65 ++++++++--------------- 3 files changed, 102 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 4c24ac6206..96c3210c66 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,33 @@ Invoke is available in two editions: More detail, including hardware requirements and manual install instructions, are available in the [installation documentation][installation docs]. +## Docker Container + +We publish official container images in Github Container Registry: https://github.com/invoke-ai/InvokeAI/pkgs/container/invokeai. Both CUDA and ROCm images are available. Check the above link for relevant tags. + +> [!IMPORTANT] +> Ensure that Docker is set up to use the GPU. Refer to [NVIDIA][nvidia docker docs] or [AMD][amd docker docs] documentation. + +### Generate! + +Run the container, modifying the command as necessary: + +```bash +docker run --runtime=nvidia --gpus=all --publish 9090:9090 ghcr.io/invoke-ai/invokeai +``` + +Then open `http://localhost:9090` and install some models using the Model Manager tab to begin generating. + +For ROCm, add `--device /dev/kfd --device /dev/dri` to the `docker run` command. + +### Persist your data + +You will likely want to persist your workspace outside of the container. Use the `--volume /home/myuser/invokeai:/invokeai` flag to mount some local directory (using its **absolute** path) to the `/invokeai` path inside the container. Your generated images and models will reside there. You can use this directory with other InvokeAI installations, or switch between runtime directories as needed. + +### DIY + +Build your own image and customize the environment to match your needs using our `docker-compose` stack. See [README.md](./docker/README.md) in the [docker](./docker) directory. + ## Troubleshooting, FAQ and Support Please review our [FAQ][faq] for solutions to common installation problems and other issues. @@ -126,3 +153,5 @@ Original portions of the software are Copyright © 2024 by respective contributo [latest release link]: https://github.com/invoke-ai/InvokeAI/releases/latest [translation status badge]: https://hosted.weblate.org/widgets/invokeai/-/svg-badge.svg [translation status link]: https://hosted.weblate.org/engage/invokeai/ +[nvidia docker docs]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html +[amd docker docs]: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html diff --git a/docker/README.md b/docker/README.md index 9e7ac15145..fc6edeacd3 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,41 +1,75 @@ -# InvokeAI Containerized +# Invoke in Docker -All commands should be run within the `docker` directory: `cd docker` +- Ensure that Docker can use the GPU on your system +- This documentation assumes Linux, but should work similarly under Windows with WSL2 +- We don't recommend running Invoke in Docker on macOS at this time. It works, but very slowly. -## Quickstart :rocket: +## Quickstart :lightning: -On a known working Linux+Docker+CUDA (Nvidia) system, execute `./run.sh` in this directory. It will take a few minutes - depending on your internet speed - to install the core models. Once the application starts up, open `http://localhost:9090` in your browser to Invoke! +No `docker compose`, no persistence, just a simple one-liner using the official images: -For more configuration options (using an AMD GPU, custom root directory location, etc): read on. +**CUDA:** -## Detailed setup +```bash +docker run --runtime=nvidia --gpus=all --publish 9090:9090 ghcr.io/invoke-ai/invokeai +``` + +**ROCm:** + +```bash +docker run --device /dev/kfd --device /dev/dri --publish 9090:9090 ghcr.io/invoke-ai/invokeai:main-rocm +``` + +Open `http://localhost:9090` in your browser once the container finishes booting, install some models, and generate away! + +> [!TIP] +> To persist your data (including downloaded models) outside of the container, add a `--volume/-v` flag to the above command, e.g.: `docker run --volume /some/local/path:/invokeai <...the rest of the command>` + +## Customize the container + +We ship the `run.sh` script, which is a convenient wrapper around `docker compose` for cases where custom image build args are needed. Alternatively, the familiar `docker compose` commands work just as well. + +```bash +cd docker +cp .env.sample .env +# edit .env to your liking if you need to; it is well commented. +./run.sh +``` + +It will take a few minutes to build the image the first time. Once the application starts up, open `http://localhost:9090` in your browser to invoke! + +## Docker setup in detail #### Linux 1. Ensure builkit is enabled in the Docker daemon settings (`/etc/docker/daemon.json`) 2. Install the `docker compose` plugin using your package manager, or follow a [tutorial](https://docs.docker.com/compose/install/linux/#install-using-the-repository). - - The deprecated `docker-compose` (hyphenated) CLI continues to work for now. + - The deprecated `docker-compose` (hyphenated) CLI probably won't work. Update to a recent version. 3. Ensure docker daemon is able to access the GPU. - - You may need to install [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) + - [NVIDIA docs](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) + - [AMD docs](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html) #### macOS +> [!TIP] +> You'll be better off installing Invoke directly on your system, because Docker can not use the GPU on macOS. + +If you are still reading: + 1. Ensure Docker has at least 16GB RAM 2. Enable VirtioFS for file sharing 3. Enable `docker compose` V2 support -This is done via Docker Desktop preferences +This is done via Docker Desktop preferences. -### Configure Invoke environment +### Configure the Invoke Environment -1. Make a copy of `.env.sample` and name it `.env` (`cp .env.sample .env` (Mac/Linux) or `copy example.env .env` (Windows)). Make changes as necessary. Set `INVOKEAI_ROOT` to an absolute path to: - a. the desired location of the InvokeAI runtime directory, or - b. an existing, v3.0.0 compatible runtime directory. +1. Make a copy of `.env.sample` and name it `.env` (`cp .env.sample .env` (Mac/Linux) or `copy example.env .env` (Windows)). Make changes as necessary. Set `INVOKEAI_ROOT` to an absolute path to the desired location of the InvokeAI runtime directory. It may be an existing directory from a previous installation (post 4.0.0). 1. Execute `run.sh` The image will be built automatically if needed. -The runtime directory (holding models and outputs) will be created in the location specified by `INVOKEAI_ROOT`. The default location is `~/invokeai`. The runtime directory will be populated with the base configs and models necessary to start generating. +The runtime directory (holding models and outputs) will be created in the location specified by `INVOKEAI_ROOT`. The default location is `~/invokeai`. Navigate to the Model Manager tab and install some models before generating. ### Use a GPU @@ -43,9 +77,9 @@ The runtime directory (holding models and outputs) will be created in the locati - WSL2 is *required* for Windows. - only `x86_64` architecture is supported. -The Docker daemon on the system must be already set up to use the GPU. In case of Linux, this involves installing `nvidia-docker-runtime` and configuring the `nvidia` runtime as default. Steps will be different for AMD. Please see Docker documentation for the most up-to-date instructions for using your GPU with Docker. +The Docker daemon on the system must be already set up to use the GPU. In case of Linux, this involves installing `nvidia-docker-runtime` and configuring the `nvidia` runtime as default. Steps will be different for AMD. Please see Docker/NVIDIA/AMD documentation for the most up-to-date instructions for using your GPU with Docker. -To use an AMD GPU, set `GPU_DRIVER=rocm` in your `.env` file. +To use an AMD GPU, set `GPU_DRIVER=rocm` in your `.env` file before running `./run.sh`. ## Customize @@ -59,10 +93,10 @@ Values are optional, but setting `INVOKEAI_ROOT` is highly recommended. The defa INVOKEAI_ROOT=/Volumes/WorkDrive/invokeai HUGGINGFACE_TOKEN=the_actual_token CONTAINER_UID=1000 -GPU_DRIVER=nvidia +GPU_DRIVER=cuda ``` -Any environment variables supported by InvokeAI can be set here - please see the [Configuration docs](https://invoke-ai.github.io/InvokeAI/features/CONFIGURATION/) for further detail. +Any environment variables supported by InvokeAI can be set here. See the [Configuration docs](https://invoke-ai.github.io/InvokeAI/features/CONFIGURATION/) for further detail. ## Even More Customizing! diff --git a/docs/installation/040_INSTALL_DOCKER.md b/docs/installation/040_INSTALL_DOCKER.md index 3814b72e80..119cff93d2 100644 --- a/docs/installation/040_INSTALL_DOCKER.md +++ b/docs/installation/040_INSTALL_DOCKER.md @@ -4,50 +4,37 @@ title: Installing with Docker # :fontawesome-brands-docker: Docker -!!! warning "macOS and AMD GPU Users" +!!! warning "macOS users" - We highly recommend to Install InvokeAI locally using [these instructions](INSTALLATION.md), - because Docker containers can not access the GPU on macOS. - -!!! warning "AMD GPU Users" - - Container support for AMD GPUs has been reported to work by the community, but has not received - extensive testing. Please make sure to set the `GPU_DRIVER=rocm` environment variable (see below), and - use the `build.sh` script to build the image for this to take effect at build time. + Docker can not access the GPU on macOS, so your generation speeds will be slow. [Install InvokeAI](INSTALLATION.md) instead. !!! tip "Linux and Windows Users" - For optimal performance, configure your Docker daemon to access your machine's GPU. + Configure Docker to access your machine's GPU. Docker Desktop on Windows [includes GPU support](https://www.docker.com/blog/wsl-2-gpu-support-for-docker-desktop-on-nvidia-gpus/). - Linux users should install and configure the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) - -## Why containers? - -They provide a flexible, reliable way to build and deploy InvokeAI. -See [Processes](https://12factor.net/processes) under the Twelve-Factor App -methodology for details on why running applications in such a stateless fashion is important. - -The container is configured for CUDA by default, but can be built to support AMD GPUs -by setting the `GPU_DRIVER=rocm` environment variable at Docker image build time. - -Developers on Apple silicon (M1/M2/M3): You -[can't access your GPU cores from Docker containers](https://github.com/pytorch/pytorch/issues/81224) -and performance is reduced compared with running it directly on macOS but for -development purposes it's fine. Once you're done with development tasks on your -laptop you can build for the target platform and architecture and deploy to -another environment with NVIDIA GPUs on-premises or in the cloud. + Linux users should follow the [NVIDIA](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) or [AMD](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html) documentation. ## TL;DR -This assumes properly configured Docker on Linux or Windows/WSL2. Read on for detailed customization options. +Ensure your Docker setup is able to use your GPU. Then: + + ```bash + docker run --runtime=nvidia --gpus=all --publish 9090:9090 ghcr.io/invoke-ai/invokeai + ``` + +Once the container starts up, open http://localhost:9090 in your browser, install some models, and start generating. + +## Build-It-Yourself + +All the docker materials are located inside the [docker](https://github.com/invoke-ai/InvokeAI/tree/main/docker) directory in the Git repo. ```bash - # docker compose commands should be run from the `docker` directory cd docker + cp .env.sample .env docker compose up ``` -## Installation in a Linux container (desktop) +We also ship the `run.sh` convenience script. See the `docker/README.md` file for detailed instructions on how to customize the docker setup to your needs. ### Prerequisites @@ -58,18 +45,9 @@ Preferences, Resources, Advanced. Increase the CPUs and Memory to avoid this [Issue](https://github.com/invoke-ai/InvokeAI/issues/342). You may need to increase Swap and Disk image size too. -#### Get a Huggingface-Token - -Besides the Docker Agent you will need an Account on -[huggingface.co](https://huggingface.co/join). - -After you succesfully registered your account, go to -[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens), create -a token and copy it, since you will need in for the next step. - ### Setup -Set up your environmnent variables. In the `docker` directory, make a copy of `.env.sample` and name it `.env`. Make changes as necessary. +Set up your environment variables. In the `docker` directory, make a copy of `.env.sample` and name it `.env`. Make changes as necessary. Any environment variables supported by InvokeAI can be set here - please see the [CONFIGURATION](../features/CONFIGURATION.md) for further detail. @@ -103,10 +81,9 @@ Once the container starts up (and configures the InvokeAI root directory if this ## Troubleshooting / FAQ - Q: I am running on Windows under WSL2, and am seeing a "no such file or directory" error. -- A: Your `docker-entrypoint.sh` file likely has Windows (CRLF) as opposed to Unix (LF) line endings, - and you may have cloned this repository before the issue was fixed. To solve this, please change - the line endings in the `docker-entrypoint.sh` file to `LF`. You can do this in VSCode +- A: Your `docker-entrypoint.sh` might have has Windows (CRLF) line endings, depending how you cloned the repository. + To solve this, change the line endings in the `docker-entrypoint.sh` file to `LF`. You can do this in VSCode (`Ctrl+P` and search for "line endings"), or by using the `dos2unix` utility in WSL. Finally, you may delete `docker-entrypoint.sh` followed by `git pull; git checkout docker/docker-entrypoint.sh` to reset the file to its most recent version. - For more information on this issue, please see the [Docker Desktop documentation](https://docs.docker.com/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers) + For more information on this issue, see [Docker Desktop documentation](https://docs.docker.com/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers)