From 47f9eb1391e43b0a5e59329853eda116745b0bc5 Mon Sep 17 00:00:00 2001 From: Sean Sube Date: Sun, 15 Jan 2023 13:38:09 -0600 Subject: [PATCH] fix(docs): add links to GUI client at GH pages --- README.md | 88 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 59 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index f595b70b..6274d440 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,10 @@ The API runs on both Linux and Windows and provides access to the major function along with metadata about the available models and accelerators, and the output of previous runs. Hardware acceleration is supported on both AMD and Nvidia, with a CPU fallback capable of running on laptop-class machines. -The GUI runs in all major browsers, including on mobile devices, and allows you to select the model and accelerator -being used, along with the prompt and other image parameters. The last few output images are shown below the image -controls, making it easy to refer back to previous parameters or save an image from earlier. +The GUI is [hosted on Github Pages](https://ssube.github.io/onnx-web/) and runs in all major browsers, including on +mobile devices, and allows you to select the model and accelerator being used. Image parameters are shown for each of +the major modes, and you can upload or paint a mask for inpainting and outpainting. The last few output images are shown +below the image controls, making it easy to refer back to previous parameters or save an image from earlier. ![txt2img with example astronaut prompt and image](./docs/readme-preview.png) @@ -26,7 +27,7 @@ Based on guides by: - CPU software fallback - multiple schedulers - web app to generate and view images - - can be hosted alongside API or on a CDN + - [hosted on Github Pages](https://ssube.github.io/onnx-web), from your CDN, or locally - built with React and MUI - OCI containers - for both API and GUI @@ -58,12 +59,13 @@ Based on guides by: - [Download and convert models](#download-and-convert-models) - [Test the models](#test-the-models) - [Usage](#usage) + - [Running the containers](#running-the-containers) - [Configuring and running the server](#configuring-and-running-the-server) - [Securing the server](#securing-the-server) - - [Configuring and hosting the client](#configuring-and-hosting-the-client) - - [Using the web interface](#using-the-web-interface) - - [Running from containers](#running-from-containers) - - [Customizing the config](#customizing-the-config) + - [Updating the server](#updating-the-server) + - [Building the client](#building-the-client) + - [Hosting the client](#hosting-the-client) + - [Customizing the client config](#customizing-the-client-config) - [Known errors and solutions](#known-errors-and-solutions) ## Setup @@ -165,7 +167,9 @@ Install the following packages for AI: ```shell > pip install "numpy>=1.20,<1.24" + > pip install "protobuf<4,>=3.20.2" + > pip install accelerate diffusers ftfy onnx onnxruntime spacy scipy transformers ``` @@ -232,6 +236,7 @@ If you are running with an Nvidia GPU, install `onnxruntime-gpu`: ```shell > pip install onnxruntime-gpu + > pip install torch --extra-index-url https://download.pytorch.org/whl/cu117 ``` @@ -253,6 +258,10 @@ also need one of the inpainting models. Log into the HuggingFace CLI: ```shell +# on linux: +> huggingface-cli login + +# on windows: > huggingface-cli.exe login ``` @@ -296,6 +305,23 @@ If you get any errors, check [the known errors section](#known-errors-and-soluti ## Usage +### Running the containers + +OCI images are available for both the API and GUI, `ssube/onnx-web-api` and `ssube/onnx-web-gui`, respectively. These +are regularly built from the `main` branch and for all tags. + +The `ssube/onnx-web-gui` image is available in both Debian and Alpine-based versions, but the `ssube/onnx-web-api` +image is only available as a Debian-based image, due to [this Github issue with `onnxruntime`](https://github.com/microsoft/onnxruntime/issues/2909#issuecomment-593591317). + +When using the containers, make sure to mount the `models/` and `outputs/` directories. The models directory can be +read-only, but outputs should be read-write. + +```shell +> podman run -p 5000:5000 --rm -v ../models:/models:ro -v ../outputs:/outputs:rw docker.io/ssube/onnx-web-api:main-buster + +> podman run -p 8000:80 --rm docker.io/ssube/onnx-web-gui:main-nginx-bullseye +``` + ### Configuring and running the server The server relies mostly on two paths, the models and outputs. It will make sure both paths exist when it starts up, @@ -321,17 +347,38 @@ If you want to access the server from other machines on your local network, pass This will listen for requests from your current local network and may be dangerous. +You can stop the server by pressing `Ctrl+C`. + #### Securing the server When making the server publicly visible, make sure to use appropriately restrictive firewall rules along with it, and consider using a web application firewall to help prevent malicious requests. -### Configuring and hosting the client +### Updating the server -If you plan on building the GUI bundle, rather than using a hosted version, you will also need to install NodeJS 18: +Make sure to update your server occasionally. New features in the GUI may not be available on older servers, leading to +options being ignored or menus not loading correctly. + +To update the server, make sure you are on the `main` branch and pull the latest version from Github: + +```shell +> git branch +* main + +> git pull +``` + +If you want to run a specific tag of the server, run `git checkout v0.4.0` with the desired tag. + +### Building the client + +If you plan on building the GUI bundle, instead of using a hosted version [like on Github Pages](https://ssube.github.io/onnx-web), +you will also need to install NodeJS 18: - https://nodejs.org/en/download/ +If you are using Windows and Git Bash, you may not have `make` installed. You can [add some of the missing tools](https://gist.github.com/evanwill/0207876c3243bbb6863e65ec5dc3f058) from [the `ezwinports` project](https://sourceforge.net/projects/ezwinports/files/) and others. + From within the `gui/` directory, edit the `gui/examples/config.json` file so that `api.root` matches the URL printed out by the `flask run` command you ran earlier. It should look something like this: @@ -353,7 +400,7 @@ Still in the `gui/` directory, build the UI bundle and run the dev server with N > node serve.js ``` -### Using the web interface +### Hosting the client You should be able to access the web interface at http://127.0.0.1:3000/index.html or your local machine's hostname. @@ -365,24 +412,7 @@ appear on the page 10-15 seconds later (depending on your GPU and other hardware substantially longer, at least 2-3 minutes. The last four images will be shown, along with the parameters used to generate them. -### Running from containers - -OCI images are available for both the API and GUI, `ssube/onnx-web-api` and `ssube/onnx-web-gui`, respectively. These -are regularly built from the `main` branch and for all tags. - -The `ssube/onnx-web-gui` image is available in both Debian and Alpine-based versions, but the `ssube/onnx-web-api` -image is only available as a Debian-based image, due to [this Github issue with `onnxruntime`](https://github.com/microsoft/onnxruntime/issues/2909#issuecomment-593591317). - -When using the containers, make sure to mount the `models/` and `outputs/` directories. The models directory can be -read-only, but outputs should be read-write. - -```shell -> podman run -p 5000:5000 --rm -v ../models:/models:ro -v ../outputs:/outputs:rw docker.io/ssube/onnx-web-api:main-buster - -> podman run -p 8000:80 --rm docker.io/ssube/onnx-web-gui:main-nginx-bullseye -``` - -### Customizing the config +### Customizing the client config You can customize the config file if you want to change the default model, platform (hardware acceleration), scheduler, and prompt. If you have a good base prompt or always want to use the CPU fallback, you can set that in the config file: