Skip to content

Commit 6b5e0e3

Browse files
SBrandeisSBrandeis
committed
sketch out Dev Mode docs
1 parent 8736fb4 commit 6b5e0e3

File tree

3 files changed

+156
-0
lines changed

3 files changed

+156
-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: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
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+
The Dev Mode of Spaces is a tool 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+
<img src="https://cdn-uploads.huggingface.co/production/uploads/5f17f0a0925b9863e28ad517/wSfCELm8WoY_EFhj8l1MM.png" style="max-width: 500px;">
33+
34+
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.
35+
36+
<div class="alert alert-warning">
37+
If you're using the Streamlit or Gradio SDK, or if your application is Pyhton-based, note that requirements are not installed automatically.
38+
You will need to manually run `pip install` from VS Code or SSH.
39+
</div>
40+
41+
### Persisting changes
42+
43+
<div class="alert alert-warning">
44+
The changes you make when Dev Mode is enabled are not persisted to the Space repo automatically.
45+
By default, they will be discarded when Dev Mode is disabled or when the Space goes to sleep.
46+
</div>
47+
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:
48+
49+
```shell
50+
# Add changes and commit them
51+
git add .
52+
git commit -m "Persist changes from Dev Mode"
53+
54+
# Push the commit to persist them in the repo
55+
git push
56+
```
57+
58+
The modal will display a warning if you have uncommitted or unpushed changes in the Space:
59+
60+
61+
![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/r6Uk1YyvE2-hzsKTSRvnR.png)
62+
63+
64+
## Enabling Dev Mode
65+
66+
You can enable the Dev Mode on your Space from the web interface.
67+
68+
<div class="flex justify-center" style="max-width: 550px">
69+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO.png" alt="screenshot of the dev mode toggle from the contextual menu."/>
70+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO-dark.png" alt="screenshot of the dev mode toggle from the contextual menu."/>
71+
</div>
72+
73+
<div class="flex justify-center" style="max-width: 550px">
74+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO.png" alt="screenshot of the dev mode toggle from the Space settings."/>
75+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO-dark.png" alt="screenshot of the dev mode toggle from the Space settings."/>
76+
</div>
77+
78+
<div class="flex justify-center" style="max-width: 550px">
79+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO.png" alt="screenshot of the dev mode toggle from the Space logs."/>
80+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO-dark.png" alt="screenshot of the dev mode toggle from the Space logs."/>
81+
</div>
82+
83+
You can also create a Space with the dev mode enabled:
84+
85+
<div class="flex justify-center" style="max-width: 550px">
86+
<img class="block dark:hidden !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO.png" alt="screenshot of the dev mode toggle from the Space creation page."/>
87+
<img class="hidden dark:block !m-0" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/TODO-dark.png" alt="screenshot of the dev mode toggle from the Space creation page."/>
88+
</div>
89+
90+
91+
## Limitations
92+
93+
Dev Mode is currently not available for static Spaces. Docker Spaces also have some additional requirements.
94+
95+
### Docker Spaces
96+
97+
Dev Mode is supported for Docker Spaces. However, your Space needs to comply with the following rules for Dev Mode to work properly.
98+
99+
1. The following packages must be installed:
100+
101+
- `bash` (required to establish SSH connections)
102+
- `curl`, `wget` and `procps` (required by the VS Code server process)
103+
- `git` and `git-lfs` to be able to commit and push changes from your Dev Mode environment
104+
105+
2. Your application code must be located in the `/app` folder for the Dev Mode daemon to be able to detect changes.
106+
107+
3. The `/app` folder must be owned by the user with uid `1000` to allow you to make changes to the code.
108+
109+
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.
110+
111+
Dev Mode works well when the base image is debian-based (eg, ubuntu).
112+
113+
More exotic linux distros (eg, alpine) are not tested and Dev Mode is not guaranteed to work on them.
114+
115+
### Example of compatible Dockerfiles
116+
117+
This is an example of a Dockerfile compatible with Spaces Dev Mode.
118+
119+
It installs the required packages with `apt-get`, along with a couple more for developer convenience (namely: `top`, `vim` and `nano`).
120+
It then starts a NodeJS application from `/app`.
121+
122+
```Dockerfile
123+
FROM node:19-slim
124+
125+
RUN apt-get update && \
126+
apt-get install -y \
127+
bash \
128+
git git-lfs \
129+
wget curl procps \
130+
htop vim nano && \
131+
rm -rf /var/lib/apt/lists/*
132+
133+
134+
WORKDIR /app
135+
COPY --link ./ /app
136+
RUN npm i
137+
138+
RUN chown 1000 /app
139+
USER 1000
140+
CMD ["node", "index.js"]
141+
```
142+
143+
There are several examples of Dev Mode compatible Docker Spaces in this organization.
144+
Feel free to duplicate them in your namespace!
145+
146+
Example Python app (FastAPI HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-python
147+
148+
Example Javascript app (Express.js HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-javascript
149+
150+
151+
## Feedback
152+
153+
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)