Skip to content

Commit fbd46c4

Browse files
SBrandeisgary149
SBrandeis
and
gary149
authored
[Spaces] Document Dev Mode (#1498)
* sketch out Dev Mode docs * images + VS Code / SSH instructions * Update docs/hub/spaces-dev-mode.md Co-authored-by: Victor Muštar <[email protected]> --------- Co-authored-by: Victor Muštar <[email protected]>
1 parent 4f24a61 commit fbd46c4

File tree

3 files changed

+172
-0
lines changed

3 files changed

+172
-0
lines changed

‎docs/hub/_toctree.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,8 @@
242242
title: Spaces GPU Upgrades
243243
- local: spaces-zerogpu
244244
title: Spaces ZeroGPU
245+
- local: spaces-dev-mode
246+
title: Spaces Dev Mode
245247
- local: spaces-storage
246248
title: Spaces Persistent Storage
247249
- local: spaces-sdks-gradio

‎docs/hub/spaces-dev-mode.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Spaces Dev Mode: Seamless development in Spaces
2+
3+
<Tip warning={true}>
4+
This feature is still in Beta stage.
5+
</Tip>
6+
7+
<Tip warning={true}>
8+
The Spaces Dev Mode is part of PRO and Enterprise Hub subscriptions.
9+
</Tip>
10+
11+
## Spaces Dev Mode
12+
13+
Spaces Dev Mode is a feature that eases the debugging of your application and makes iterating on Spaces faster.
14+
15+
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.
16+
17+
The Dev Mode allows you to update your Space much quicker by overriding the Docker image.
18+
19+
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.
20+
21+
The ability to connect to the running Space unlocks several use cases:
22+
23+
- You can make changes to the app code without the Space rebuilding everytime
24+
- You can debug a running application and monitor resources live
25+
26+
Overall it makes developing and experimenting with Spaces much faster by skipping the Docker image rebuild phase.
27+
28+
## Interface
29+
30+
Once the Dev Mode is enabled on your Space, you should see a modal like the following.
31+
32+
<div class="flex justify-center" style="max-width: 550px">
33+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-controls.png" alt="screenshot of the dev mode controls interface."/>
34+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-controls-dark.png" alt="screenshot of the dev mode controls interface."/>
35+
</div>
36+
37+
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+
39+
<div class="alert alert-warning">
40+
If you're using the Streamlit or Gradio SDK, or if your application is Pyhton-based, note that requirements are not installed automatically.
41+
You will need to manually run `pip install` from VS Code or SSH.
42+
</div>
43+
44+
### SSH connection and VS Code
45+
46+
The Dev Mode allows you to connect to your Space's docker container using SSH.
47+
48+
Instructions to connect are listed in the Dev Mode controls modal.
49+
50+
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.
51+
Check out the [Git over SSH](./security-git-ssh#add-a-ssh-key-to-your-account) documentation for more detailed instructions.
52+
53+
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.
54+
55+
### Persisting changes
56+
57+
<div class="alert alert-warning">
58+
The changes you make when Dev Mode is enabled are not persisted to the Space repo automatically.
59+
By default, they will be discarded when Dev Mode is disabled or when the Space goes to sleep.
60+
</div>
61+
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:
62+
63+
```shell
64+
# Add changes and commit them
65+
git add .
66+
git commit -m "Persist changes from Dev Mode"
67+
68+
# Push the commit to persist them in the repo
69+
git push
70+
```
71+
72+
The modal will display a warning if you have uncommitted or unpushed changes in the Space:
73+
74+
75+
<div class="flex justify-center" style="max-width: 550px">
76+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-controls-uncommitted.png" alt="screenshot of the dev mode controls interface."/>
77+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-controls-uncommitted-dark.png" alt="screenshot of the dev mode controls interface."/>
78+
</div>
79+
80+
## Enabling Dev Mode
81+
82+
You can enable the Dev Mode on your Space from the web interface.
83+
84+
<div class="flex justify-center" style="max-width: 550px">
85+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-enable-contextual.png" alt="screenshot of the dev mode toggle from the contextual menu."/>
86+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-enable-contextual-dark.png" alt="screenshot of the dev mode toggle from the contextual menu."/>
87+
</div>
88+
89+
<div class="flex justify-center" style="max-width: 550px">
90+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-enable-settings.png" alt="screenshot of the dev mode toggle from the Space settings."/>
91+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-enable-settings-dark.png" alt="screenshot of the dev mode toggle from the Space settings."/>
92+
</div>
93+
94+
<div class="flex justify-center" style="max-width: 550px">
95+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-enable-logs.png" alt="screenshot of the dev mode toggle from the Space logs."/>
96+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-enable-logs-dark.png" alt="screenshot of the dev mode toggle from the Space logs."/>
97+
</div>
98+
99+
You can also create a Space with the dev mode enabled:
100+
101+
<div class="flex justify-center" style="max-width: 550px">
102+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-creation-enable.png" alt="screenshot of the dev mode toggle from the Space creation page."/>
103+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-dev-mode/dev-mode-creation-enable-dark.png" alt="screenshot of the dev mode toggle from the Space creation page."/>
104+
</div>
105+
106+
107+
## Limitations
108+
109+
Dev Mode is currently not available for static Spaces. Docker Spaces also have some additional requirements.
110+
111+
### Docker Spaces
112+
113+
Dev Mode is supported for Docker Spaces. However, your Space needs to comply with the following rules for Dev Mode to work properly.
114+
115+
1. The following packages must be installed:
116+
117+
- `bash` (required to establish SSH connections)
118+
- `curl`, `wget` and `procps` (required by the VS Code server process)
119+
- `git` and `git-lfs` to be able to commit and push changes from your Dev Mode environment
120+
121+
2. Your application code must be located in the `/app` folder for the Dev Mode daemon to be able to detect changes.
122+
123+
3. The `/app` folder must be owned by the user with uid `1000` to allow you to make changes to the code.
124+
125+
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.
126+
127+
Dev Mode works well when the base image is debian-based (eg, ubuntu).
128+
129+
More exotic linux distros (eg, alpine) are not tested and Dev Mode is not guaranteed to work on them.
130+
131+
### Example of compatible Dockerfiles
132+
133+
This is an example of a Dockerfile compatible with Spaces Dev Mode.
134+
135+
It installs the required packages with `apt-get`, along with a couple more for developer convenience (namely: `top`, `vim` and `nano`).
136+
It then starts a NodeJS application from `/app`.
137+
138+
```Dockerfile
139+
FROM node:19-slim
140+
141+
RUN apt-get update && \
142+
apt-get install -y \
143+
bash \
144+
git git-lfs \
145+
wget curl procps \
146+
htop vim nano && \
147+
rm -rf /var/lib/apt/lists/*
148+
149+
150+
WORKDIR /app
151+
COPY --link ./ /app
152+
RUN npm i
153+
154+
RUN chown 1000 /app
155+
USER 1000
156+
CMD ["node", "index.js"]
157+
```
158+
159+
There are several examples of Dev Mode compatible Docker Spaces in this organization.
160+
Feel free to duplicate them in your namespace!
161+
162+
Example Python app (FastAPI HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-python
163+
164+
Example Javascript app (Express.js HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-javascript
165+
166+
167+
## Feedback
168+
169+
You can share your feedback on Spaces Dev Mode directly on the HF Hub: https://huggingface.co/spaces/dev-mode-explorers/README/discussions

‎docs/hub/spaces.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ You'll also be able to upgrade your Space to run [on a GPU or other accelerated
1616
- [More ways to create Spaces](./spaces-more-ways-to-create)
1717
- [Managing Spaces with Github Actions](./spaces-github-actions)
1818
- [How to Add a Space to ArXiv](./spaces-add-to-arxiv)
19+
- [Spaces Dev Mode](./spaces-dev-mode)
1920
- [Spaces GPU Upgrades](./spaces-gpus)
2021
- [Spaces Persistent Storage](./spaces-storage)
2122
- [Gradio Spaces](./spaces-sdks-gradio)

0 commit comments

Comments
 (0)