Merge branch 'main' into update/docker/include-dockerhub

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![project logo](https://github.com/mauwii/InvokeAI/raw/main/docs/assets/invoke_ai_banner.png)
+![project logo](https://github.com/invoke-ai/InvokeAI/raw/main/docs/assets/invoke_ai_banner.png)
 
 # InvokeAI: A Stable Diffusion Toolkit
 
@@ -41,38 +41,136 @@ requests. Be sure to use the provided templates. They will help us diagnose issu
 
 <div align="center">
 
-![canvas preview](https://github.com/mauwii/InvokeAI/raw/main/docs/assets/canvas_preview.png)
+![canvas preview](https://github.com/invoke-ai/InvokeAI/raw/main/docs/assets/canvas_preview.png)
 
 </div>
 
-# Getting Started with InvokeAI
+## Table of Contents
+
+1. [Quick Start](#getting-started-with-invokeai)
+2. [Installation](#detailed-installation-instructions)
+3. [Hardware Requirements](#hardware-requirements)
+4. [Features](#features)
+5. [Latest Changes](#latest-changes)
+6. [Troubleshooting](#troubleshooting)
+7. [Contributing](#contributing)
+8. [Contributors](#contributors)
+9. [Support](#support)
+10. [Further Reading](#further-reading)
+
+## Getting Started with InvokeAI
 
 For full installation and upgrade instructions, please see:
 [InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/)
 
+### Automatic Installer (suggested for 1st time users)
+
 1. Go to the bottom of the [Latest Release Page](https://github.com/invoke-ai/InvokeAI/releases/latest)
+
 2. Download the .zip file for your OS (Windows/macOS/Linux).
+
 3. Unzip the file.
-4. If you are on Windows, double-click on the `install.bat` script. On macOS, open a Terminal window, drag the file `install.sh` from Finder into the Terminal, and press return. On Linux, run `install.sh`.
-5. Wait a while, until it is done.
-6. The folder where you ran the installer from will now be filled with lots of files. If you are on Windows, double-click on the `invoke.bat` file. On macOS, open a Terminal window, drag `invoke.sh` from the folder into the Terminal, and press return. On Linux, run `invoke.sh`
-7. Press 2 to open the "browser-based UI", press enter/return, wait a minute or two for Stable Diffusion to start up, then open your browser and go to http://localhost:9090.
-8. Type `banana sushi` in the box on the top left and click `Invoke`
 
+4. If you are on Windows, double-click on the `install.bat` script. On
+macOS, open a Terminal window, drag the file `install.sh` from Finder
+into the Terminal, and press return. On Linux, run `install.sh`.
 
-## Table of Contents
+5. You'll be asked to confirm the location of the folder in which
+to install InvokeAI and its image generation model files. Pick a
+location with at least 15 GB of free memory. More if you plan on
+installing lots of models.
 
-1. [Installation](#installation)
+6. Wait while the installer does its thing. After installing the software,
-2. [Hardware Requirements](#hardware-requirements)
+the installer will launch a script that lets you configure InvokeAI and
-3. [Features](#features)
+select a set of starting image generaiton models.
-4. [Latest Changes](#latest-changes)
-5. [Troubleshooting](#troubleshooting)
-6. [Contributing](#contributing)
-7. [Contributors](#contributors)
-8. [Support](#support)
-9. [Further Reading](#further-reading)
 
-## Installation
+7. Find the folder that InvokeAI was installed into (it is not the
+same as the unpacked zip file directory!) The default location of this
+folder (if you didn't change it in step 5) is `~/invokeai` on
+Linux/Mac systems, and `C:\Users\YourName\invokeai` on Windows. This directory will contain launcher scripts named `invoke.sh` and `invoke.bat`.
+
+8. On Windows systems, double-click on the `invoke.bat` file. On
+macOS, open a Terminal window, drag `invoke.sh` from the folder into
+the Terminal, and press return. On Linux, run `invoke.sh`
+
+9. Press 2 to open the "browser-based UI", press enter/return, wait a
+minute or two for Stable Diffusion to start up, then open your browser
+and go to http://localhost:9090.
+
+10. Type `banana sushi` in the box on the top left and click `Invoke`
+
+### Command-Line Installation (for users familiar with Terminals)
+
+You must have Python 3.9 or 3.10 installed on your machine. Earlier or later versions are
+not supported.
+
+1. Open a command-line window on your machine. The PowerShell is recommended for Windows.
+2. Create a directory to install InvokeAI into. You'll need at least 15 GB of free space:
+
+    ```terminal
+    mkdir invokeai
+    ````
+
+3. Create a virtual environment named `.venv` inside this directory and activate it:
+
+    ```terminal
+    cd invokeai
+    python -m venv .venv --prompt InvokeAI
+    ```
+
+4. Activate the virtual environment (do it every time you run InvokeAI)
+
+    _For Linux/Mac users:_
+
+    ```sh
+    source .venv/bin/activate
+    ```
+
+    _For Windows users:_
+
+    ```ps
+    .venv\Scripts\activate
+    ```
+
+5. Install the InvokeAI module and its dependencies. Choose the command suited for your platform & GPU.
+
+    _For Windows/Linux with an NVIDIA GPU:_
+
+    ```terminal
+    pip install InvokeAI[xformers] --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117
+    ```
+
+    _For Linux with an AMD GPU:_
+
+    ```sh
+    pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.2
+    ```
+
+    _For Macintoshes, either Intel or M1/M2:_
+
+    ```sh
+    pip install InvokeAI --use-pep517
+    ```
+
+6. Configure InvokeAI and install a starting set of image generation models (you only need to do this once):
+
+    ```terminal
+    invokeai-configure
+    ```
+
+7. Launch the web server (do it every time you run InvokeAI):
+
+    ```terminal
+    invokeai --web
+    ```
+
+8. Point your browser to http://localhost:9090 to bring up the web interface.
+9. Type `banana sushi` in the box on the top left and click `Invoke`.
+
+Be sure to activate the virtual environment each time before re-launching InvokeAI,
+using `source .venv/bin/activate` or `.venv\Scripts\activate`.
+
+### Detailed Installation Instructions
 
 This fork is supported across Linux, Windows and Macintosh. Linux
 users can use either an Nvidia-based card (with CUDA support) or an
@@ -80,13 +178,13 @@ AMD card (using the ROCm driver). For full installation and upgrade
 instructions, please see:
 [InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/INSTALL_SOURCE/)
 
-### Hardware Requirements
+## Hardware Requirements
 
 InvokeAI is supported across Linux, Windows and macOS. Linux
 users can use either an Nvidia-based card (with CUDA support) or an
 AMD card (using the ROCm driver).
 
-#### System
+### System
 
 You will need one of the following:
 
@@ -98,11 +196,11 @@ We do not recommend the GTX 1650 or 1660 series video cards. They are
 unable to run in half-precision mode and do not have sufficient VRAM
 to render 512x512 images.
 
-#### Memory
+### Memory
 
 - At least 12 GB Main Memory RAM.
 
-#### Disk
+### Disk
 
 - At least 12 GB of free disk space for the machine learning model, Python, and all its dependencies.
 
@@ -152,7 +250,7 @@ Notes](https://github.com/invoke-ai/InvokeAI/releases) and the
 Please check out our **[Q&A](https://invoke-ai.github.io/InvokeAI/help/TROUBLESHOOT/#faq)** to get solutions for common installation
 problems and other issues.
 
-# Contributing
+## Contributing
 
 Anyone who wishes to contribute to this project, whether documentation, features, bug fixes, code
 cleanup, testing, or code reviews, is very much encouraged to do so.

docs/installation/020_INSTALL_MANUAL.md

@@ -30,25 +30,35 @@ Installation](010_INSTALL_AUTOMATED.md), and in many cases will
 already be installed (if, for example, you have used your system for
 gaming):
 
-* **Python** version 3.9 or 3.10 (3.11 is not recommended).
+* **Python**
 
-* **CUDA Tools** For those with _NVidia GPUs_, you will need to
+    version 3.9 or 3.10 (3.11 is not recommended).
-  install the [CUDA toolkit and optionally the XFormers library](070_INSTALL_XFORMERS.md).
 
-*  **ROCm Tools** For _Linux users with AMD GPUs_, you will need
+* **CUDA Tools**
-   to install the [ROCm toolkit](./030_INSTALL_CUDA_AND_ROCM.md). Note that
-   InvokeAI does not support AMD GPUs on Windows systems due to
-   lack of a Windows ROCm library.
 
-*  **Visual C++ Libraries** _Windows users_ must install the free
+    For those with _NVidia GPUs_, you will need to
-   [Visual C++ libraries from Microsoft](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170)
+    install the [CUDA toolkit and optionally the XFormers library](070_INSTALL_XFORMERS.md).
 
-* **The Xcode command line tools** for _Macintosh users_. Instructions are
+* **ROCm Tools**
-  available at [Free Code Camp](https://www.freecodecamp.org/news/install-xcode-command-line-tools/)
 
-* _Macintosh users_ may also need to run the `Install Certificates` command
+    For _Linux users with AMD GPUs_, you will need
-  if model downloads give lots of certificate errors. Run:
+    to install the [ROCm toolkit](./030_INSTALL_CUDA_AND_ROCM.md). Note that
-  `/Applications/Python\ 3.10/Install\ Certificates.command`
+    InvokeAI does not support AMD GPUs on Windows systems due to
+    lack of a Windows ROCm library.
+
+* **Visual C++ Libraries**
+
+    _Windows users_ must install the free
+    [Visual C++ libraries from Microsoft](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170)
+
+* **The Xcode command line tools**
+
+    for _Macintosh users_. Instructions are available at
+    [Free Code Camp](https://www.freecodecamp.org/news/install-xcode-command-line-tools/)
+
+    * _Macintosh users_ may also need to run the `Install Certificates` command
+      if model downloads give lots of certificate errors. Run:
+      `/Applications/Python\ 3.10/Install\ Certificates.command`
 
 ### Installation Walkthrough
 
@@ -75,7 +85,7 @@ manager, please follow these steps:
     === "Linux/Mac"
 
         ```bash
-        export INVOKEAI_ROOT="~/invokeai"
+        export INVOKEAI_ROOT=~/invokeai
         mkdir $INVOKEAI_ROOT
         ```
 
@@ -99,35 +109,30 @@ manager, please follow these steps:
    Windows environment variable using the Advanced System Settings dialogue.
    Refer to your operating system documentation for details.
 
-
+    ```terminal
-    === "Linux/Mac"
+    cd $INVOKEAI_ROOT
-        ```bash
+    python -m venv .venv --prompt InvokeAI
-        cd $INVOKEAI_ROOT
+    ```
-        python -m venv create .venv
-        ```
-
-    === "Windows"
-         ```bash
-         cd $INVOKEAI_ROOT
-     	 python -m venv create .venv
-     	 ```
 
 4.  Activate the new environment:
 
     === "Linux/Mac"
-    	```bash
+
+        ```bash
         source .venv/bin/activate
-    	```
+        ```
 
     === "Windows"
-    	```bash
-        .venv\script\activate
-    	```
-	If you get a permissions error at this point, run the command
-	`Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser`
-	and try `activate` again.
 
-    The command-line prompt should change to to show `(.venv)` at the
+        ```ps
+        .venv\script\activate
+        ```
+
+        If you get a permissions error at this point, run this command and try again
+
+        `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
+
+    The command-line prompt should change to to show `(InvokeAI)` at the
     beginning of the prompt. Note that all the following steps should be
     run while inside the INVOKEAI_ROOT directory
 
@@ -137,40 +142,47 @@ manager, please follow these steps:
     python -m pip install --upgrade pip
     ```
 
-6.  Install the InvokeAI Package. The `--extra-index-url` option is used to select among CUDA, ROCm and CPU/MPS drivers as shown below:
+6. Install the InvokeAI Package. The `--extra-index-url` option is used to select among
+   CUDA, ROCm and CPU/MPS drivers as shown below:
 
     === "CUDA (NVidia)"
+
         ```bash
         pip install InvokeAI[xformers] --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117
         ```
 
     === "ROCm (AMD)"
+
         ```bash
         pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.2
         ```
 
     === "CPU (Intel Macs & non-GPU systems)"
+
         ```bash
         pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/cpu
         ```
 
     === "MPS (M1 and M2 Macs)"
+
         ```bash
-        pip install InvokeAI --use-pep517  --extra-index-url https://download.pytorch.org/whl/cpu
+        pip install InvokeAI --use-pep517
         ```
 
 7.  Deactivate and reactivate your runtime directory so that the invokeai-specific commands
     become available in the environment
 
     === "Linux/Macintosh"
+
         ```bash
         deactivate && source .venv/bin/activate
         ```
 
     === "Windows"
-        ```bash
+
+        ```ps
         deactivate
-	.venv\Scripts\activate
+        .venv\Scripts\activate
         ```
 
 8.  Set up the runtime directory
@@ -179,7 +191,7 @@ manager, please follow these steps:
     models, model config files, directory for textual inversion embeddings, and
     your outputs.
 
-    ```bash
+    ```terminal
     invokeai-configure
     ```
 
@@ -314,7 +326,7 @@ installation protocol (important!)
 
     === "MPS (M1 and M2 Macs)"
         ```bash
-        pip install -e . --use-pep517  --extra-index-url https://download.pytorch.org/whl/cpu
+        pip install -e . --use-pep517
         ```
 
     Be sure to pass `-e` (for an editable install) and don't forget the
@@ -332,3 +344,27 @@ installation protocol (important!)
 
     Please see [Contributing](/index.md#Contributing) for hints
     on getting started.
+
+### Unsupported Conda Install
+
+Congratulations, you found the "secret" Conda installation
+instructions. If you really **really** want to use Conda with InvokeAI
+you can do so using this unsupported recipe:
+
+```
+mkdir ~/invokeai
+conda create -n invokeai python=3.10
+conda activate invokeai
+pip install InvokeAI[xformers] --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117
+invokeai-configure --root ~/invokeai
+invokeai --root ~/invokeai --web
+```
+
+The `pip install` command shown in this recipe is for Linux/Windows
+systems with an NVIDIA GPU. See step (6) above for the command to use
+with other platforms/GPU combinations. If you don't wish to pass the
+`--root` argument to `invokeai` with each launch, you may set the
+environment variable INVOKEAI_ROOT to point to the installation directory.
+
+Note that if you run into problems with the Conda installation, the InvokeAI
+staff will **not** be able to help you out. Caveat Emptor!