Add HF Storage Bucket persistence support (#8)

- Add HF Storage Bucket persistence support (45864bb8300898c940880c7ce905906cee795c68)


Co-authored-by: Daniel van Strien <davanstrien@users.noreply.huggingface.co>

Dockerfile

@@ -33,8 +33,8 @@ FROM heartexlabs/label-studio:hf-latest
 # annotation data in the space will be lost. You can enable configuration
 # persistence through one of two methods:
 #
-# 1) Enabling Hugging Face Persistent Storage for saving project and annotation
-#    settings, as well as local task storage.
+# 1) Attaching an HF Storage Bucket for persisting the SQLite database and
+#    media uploads across restarts (recommended).
 # 2) Connecting an external Postgres database for saving project and annotation
 #    settings, and cloud by connecting cloud storage for tasks.
 #
@@ -42,20 +42,24 @@ FROM heartexlabs/label-studio:hf-latest
 
 ################################################################################
 #
-# How to Enable Hugging Face Persistent Storage for Label Studio
-# --------------------------------------------------------------
+# How to Enable Persistence with HF Storage Buckets
+# --------------------------------------------------
 #
-# In the Hugging Face Label Studio Space settings, select the appropriate
-# Persistent Storage tier. Note that Persistent Storage is a paid add-on.
-# By default, persistent storage is mounted to /data. In your Space settings,
-# set the following variables:
+# HF Storage Buckets provide persistent object storage that can be
+# mounted directly into your Space. Label Studio will write its SQLite
+# database and media uploads into the mounted bucket, so everything
+# survives restarts.
 #
-# LABEL_STUDIO_BASE_DATA_DIR=/data
-# ENV STORAGE_PERSISTENCE=1
+# 1. Create a bucket:  hf buckets create <namespace>/label-studio-data
+# 2. Attach it in Space Settings → Storage Buckets, mount path: /data
+# 3. Set Space Variables:
+#      LABEL_STUDIO_BASE_DATA_DIR=/data
+#      STORAGE_PERSISTENCE=1
+# 4. (Recommended) Set a SECRET_KEY Space Secret to keep user sessions
+#    alive across restarts.
+# 5. Factory rebuild the Space.
 #
-# Your space will restart. NOTE: if you have existing settings and data,
-# they will be lost in this first restart. Data and setting will only be
-# preserved on subsequent restarts of the space.
+# See https://huggingface.co/docs/hub/storage-buckets for more details.
 #
 ################################################################################
 
@@ -124,4 +128,9 @@ FROM heartexlabs/label-studio:hf-latest
 #
 ################################################################################
 
+# The upstream base image runs as UID 1001. HF Storage Bucket mounts currently
+# require root to write. This can be removed once bucket mounts support
+# non-root UIDs natively.
+USER root
+
 CMD exec label-studio --host=$SPACE_HOST

README.md

@@ -45,8 +45,10 @@ After logging in, Label Studio will present you with a project view. Here you
 can create a new project with prompts to upload data and set up a custom
 configuration interface.
 
-**Note that in the default configuration, storage is local and temporary. Any
-projects, annotations, and configurations will be lost if the space is restarted.**
+**Note that in the default configuration, storage is local and temporary.** To
+persist your projects and annotations across restarts, attach an
+[HF Storage Bucket](https://huggingface.co/docs/hub/storage-buckets) — see the
+persistence section below.
 
 ## Next Steps and Additional Resources
 
@@ -83,29 +85,38 @@ You will need to provide new users with an invitation link to join the space,
 which can be found in the Organizations interface of Label Studio.
 
 By default this space stores all project configuration and data annotations
-in local storage with Sqlite. If the space is reset, all configuration and
-annotation data in the space will be lost. You can enable configuration
-persistence in one of two ways:
+in local storage with SQLite. If the space is reset, all configuration and
+annotation data in the space will be lost. You can enable persistence in one
+of two ways:
 
-1. Enabling Persistent Storage in your Space settings and configuring Label
-   Studio to write its database and task storage there.
+1. Attaching an HF Storage Bucket (recommended).
 
 2. Connecting an external Postgres database and cloud storage to your space,
    guaranteeing that all project and annotation settings are preserved.
 
-### Enabling Hugging Face Persistent Storage
+### Persistence with HF Storage Buckets
 
-In the Hugging Face Label Studio Space settings, select the appropriate
-Persistent Storage tier. Note that Persistent Storage is a paid add-on.
-By default, persistent storage is mounted to /data. In your Space settings,
-set the following variables:
+[HF Storage Buckets](https://huggingface.co/docs/hub/storage-buckets) provide
+persistent object storage that can be mounted directly into your Space. Label
+Studio will write its SQLite database and media uploads into the mounted bucket,
+so projects and annotations survive restarts.
 
-    LABEL_STUDIO_BASE_DATA_DIR=/data
-    ENV STORAGE_PERSISTENCE=1
+1. **Create a bucket:**
+
+       hf buckets create <your-namespace>/label-studio-data
+
+2. **Attach it** in Space Settings → Storage Buckets, mount path `/data`.
+
+3. **Set two Space Variables:**
+
+       LABEL_STUDIO_BASE_DATA_DIR=/data
+       STORAGE_PERSISTENCE=1
+
+4. **Factory rebuild** the Space.
 
-Your space will restart. NOTE: if you have existing settings and data,
-they will be lost in this first restart. Data and setting will only be
-preserved on subsequent restarts of the space.
+It is also recommended to set a `SECRET_KEY` Space Secret to keep user sessions
+alive across restarts. Without it, Label Studio generates a random key on each
+boot and all users are logged out on restart.
 
 ### Enabling Postgres Database and Cloud Storage