From 6b5e0e380c78ea231600c9bf82976ffe02050678 Mon Sep 17 00:00:00 2001 From: SBrandeis Date: Thu, 21 Nov 2024 15:54:00 +0100 Subject: [PATCH 1/3] sketch out Dev Mode docs --- docs/hub/_toctree.yml | 2 + docs/hub/spaces-dev-mode.md | 153 ++++++++++++++++++++++++++++++++++++ docs/hub/spaces.md | 1 + 3 files changed, 156 insertions(+) create mode 100644 docs/hub/spaces-dev-mode.md diff --git a/docs/hub/_toctree.yml b/docs/hub/_toctree.yml index 111807d6f..d338a9cd9 100644 --- a/docs/hub/_toctree.yml +++ b/docs/hub/_toctree.yml @@ -242,6 +242,8 @@ title: Spaces GPU Upgrades - local: spaces-zerogpu title: Spaces ZeroGPU + - local: spaces-dev-mode + title: Spaces Dev Mode - local: spaces-storage title: Spaces Persistent Storage - local: spaces-sdks-gradio diff --git a/docs/hub/spaces-dev-mode.md b/docs/hub/spaces-dev-mode.md new file mode 100644 index 000000000..74d63257e --- /dev/null +++ b/docs/hub/spaces-dev-mode.md @@ -0,0 +1,153 @@ +# Spaces Dev Mode: Seamless development in Spaces + + +This feature is still in Beta stage. + + + +The Spaces Dev Mode is part of PRO and Enterprise Hub subscriptions. + + +## Spaces Dev Mode + +The Dev Mode of Spaces is a tool that eases the debugging of your application and makes iterating on Spaces faster. + +Whenever your commit some changes to your Space repo, the underlying Docker image gets rebuilt, and then a new virtual machine is provisioned to host the new container. + +The Dev Mode allows you to update your Space much quicker by overriding the Docker image. + +The Dev Mode Docker image starts your application as a sub-process, allowing you to restart it without stopping the Space container itself. It also starts a VS Code server and a SSH server in the background for you to connect to the Space. + +The ability to connect to the running Space unlocks several use cases: + + - You can make changes to the app code without the Space rebuilding everytime + - You can debug a running application and monitor resources live + +Overall it makes developing and experimenting with Spaces much faster by skipping the Docker image rebuild phase. + +## Interface + +Once the Dev Mode is enabled on your Space, you should see a modal like the following. + + + +The application does not restart automatically when you change the code. For your changes to appear in the Space, you need to use the `Refresh` button that will restart the app. + +
+ If you're using the Streamlit or Gradio SDK, or if your application is Pyhton-based, note that requirements are not installed automatically. + You will need to manually run `pip install` from VS Code or SSH. +
+ +### Persisting changes + +
+The changes you make when Dev Mode is enabled are not persisted to the Space repo automatically. +By default, they will be discarded when Dev Mode is disabled or when the Space goes to sleep. +
+If you wish to persist changes made while Dev Mode is enabled, you need to use `git` from inside the Space container (using VS Code or SSH). For example: + +```shell +# Add changes and commit them +git add . +git commit -m "Persist changes from Dev Mode" + +# Push the commit to persist them in the repo +git push +``` + +The modal will display a warning if you have uncommitted or unpushed changes in the Space: + + +![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/r6Uk1YyvE2-hzsKTSRvnR.png) + + +## Enabling Dev Mode + +You can enable the Dev Mode on your Space from the web interface. + +
+screenshot of the dev mode toggle from the contextual menu. + +
+ +
+screenshot of the dev mode toggle from the Space settings. + +
+ +
+screenshot of the dev mode toggle from the Space logs. + +
+ +You can also create a Space with the dev mode enabled: + +
+screenshot of the dev mode toggle from the Space creation page. + +
+ + +## Limitations + +Dev Mode is currently not available for static Spaces. Docker Spaces also have some additional requirements. + +### Docker Spaces + +Dev Mode is supported for Docker Spaces. However, your Space needs to comply with the following rules for Dev Mode to work properly. + +1. The following packages must be installed: + +- `bash` (required to establish SSH connections) +- `curl`, `wget` and `procps` (required by the VS Code server process) +- `git` and `git-lfs` to be able to commit and push changes from your Dev Mode environment + +2. Your application code must be located in the `/app` folder for the Dev Mode daemon to be able to detect changes. + +3. The `/app` folder must be owned by the user with uid `1000` to allow you to make changes to the code. + +4. The Dockerfile must contain a `CMD` instruction for startup. Checkout [Docker's documentation](https://docs.docker.com/reference/dockerfile/#cmd) about the `CMD` instruction for more details. + +Dev Mode works well when the base image is debian-based (eg, ubuntu). + +More exotic linux distros (eg, alpine) are not tested and Dev Mode is not guaranteed to work on them. + +### Example of compatible Dockerfiles + +This is an example of a Dockerfile compatible with Spaces Dev Mode. + +It installs the required packages with `apt-get`, along with a couple more for developer convenience (namely: `top`, `vim` and `nano`). +It then starts a NodeJS application from `/app`. + +```Dockerfile +FROM node:19-slim + +RUN apt-get update && \ + apt-get install -y \ + bash \ + git git-lfs \ + wget curl procps \ + htop vim nano && \ + rm -rf /var/lib/apt/lists/* + + +WORKDIR /app +COPY --link ./ /app +RUN npm i + +RUN chown 1000 /app +USER 1000 +CMD ["node", "index.js"] +``` + +There are several examples of Dev Mode compatible Docker Spaces in this organization. +Feel free to duplicate them in your namespace! + +Example Python app (FastAPI HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-python + +Example Javascript app (Express.js HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-javascript + + +## Feedback + +You can share your feedback on Spaces Dev Mode directly on the HF Hub: https://huggingface.co/spaces/dev-mode-explorers/README/discussions diff --git a/docs/hub/spaces.md b/docs/hub/spaces.md index bba4da4c9..cd429d569 100644 --- a/docs/hub/spaces.md +++ b/docs/hub/spaces.md @@ -16,6 +16,7 @@ You'll also be able to upgrade your Space to run [on a GPU or other accelerated - [More ways to create Spaces](./spaces-more-ways-to-create) - [Managing Spaces with Github Actions](./spaces-github-actions) - [How to Add a Space to ArXiv](./spaces-add-to-arxiv) +- [Spaces Dev Mode](./spaces-dev-mode) - [Spaces GPU Upgrades](./spaces-gpus) - [Spaces Persistent Storage](./spaces-storage) - [Gradio Spaces](./spaces-sdks-gradio) From 262c98e34bbc6bba259973c94d1f522b488b3187 Mon Sep 17 00:00:00 2001 From: SBrandeis Date: Thu, 21 Nov 2024 16:55:28 +0100 Subject: [PATCH 2/3] images + VS Code / SSH instructions --- docs/hub/spaces-dev-mode.md | 38 ++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/hub/spaces-dev-mode.md b/docs/hub/spaces-dev-mode.md index 74d63257e..934d65f15 100644 --- a/docs/hub/spaces-dev-mode.md +++ b/docs/hub/spaces-dev-mode.md @@ -29,7 +29,10 @@ Overall it makes developing and experimenting with Spaces much faster by skippin Once the Dev Mode is enabled on your Space, you should see a modal like the following. - +
+screenshot of the dev mode controls interface. + +
The application does not restart automatically when you change the code. For your changes to appear in the Space, you need to use the `Refresh` button that will restart the app. @@ -38,6 +41,17 @@ The application does not restart automatically when you change the code. For you You will need to manually run `pip install` from VS Code or SSH. +### SSH connection and VS Code + +The Dev Mode allows you to connect to your Space's docker container using SSH. + +Instructions to connect are listed in the Dev Mode controls modal. + +You will need to add your machine's SSH public key to [your user account](https://huggingface.co/settings/keys) to be able to connect to the Space using SSH. +Check out the [Git over SSH](./security-git-ssh#add-a-ssh-key-to-your-account) documentation for more detailed instructions. + +You can also use a local install of VS Code to connect to the Space container. To do so, you will need to install the [SSH Remote](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension. + ### Persisting changes
@@ -58,33 +72,35 @@ git push The modal will display a warning if you have uncommitted or unpushed changes in the Space: -![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/r6Uk1YyvE2-hzsKTSRvnR.png) - +
+screenshot of the dev mode controls interface. + +
## Enabling Dev Mode You can enable the Dev Mode on your Space from the web interface.
-screenshot of the dev mode toggle from the contextual menu. - +screenshot of the dev mode toggle from the contextual menu. +
-screenshot of the dev mode toggle from the Space settings. - +screenshot of the dev mode toggle from the Space settings. +
-screenshot of the dev mode toggle from the Space logs. - +screenshot of the dev mode toggle from the Space logs. +
You can also create a Space with the dev mode enabled:
-screenshot of the dev mode toggle from the Space creation page. - +screenshot of the dev mode toggle from the Space creation page. +
From b9e3b19e8139b656d31296ac19d055b6f7f7b37f Mon Sep 17 00:00:00 2001 From: Simon Brandeis <33657802+SBrandeis@users.noreply.github.com> Date: Fri, 22 Nov 2024 10:33:50 +0100 Subject: [PATCH 3/3] Update docs/hub/spaces-dev-mode.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Victor Muštar --- docs/hub/spaces-dev-mode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/spaces-dev-mode.md b/docs/hub/spaces-dev-mode.md index 934d65f15..07e00c5b2 100644 --- a/docs/hub/spaces-dev-mode.md +++ b/docs/hub/spaces-dev-mode.md @@ -10,7 +10,7 @@ The Spaces Dev Mode is part of PRO and Enterprise Hub subscriptions. ## Spaces Dev Mode -The Dev Mode of Spaces is a tool that eases the debugging of your application and makes iterating on Spaces faster. +Spaces Dev Mode is a feature that eases the debugging of your application and makes iterating on Spaces faster. Whenever your commit some changes to your Space repo, the underlying Docker image gets rebuilt, and then a new virtual machine is provisioned to host the new container.