Add: Autostart

Dockerfile

@@ -7,7 +7,7 @@ ARG Z2JH_VERSION=4.3.1
 # then copy over just the built wheel files for the final image.
 # This keeps image size low while also making the whole process
 # reasonably simple
-FROM quay.io/jupyterhub/k8s-hub:${Z2JH_VERSION} as builder
+FROM quay.io/jupyterhub/k8s-hub:${Z2JH_VERSION} AS builder
 
 USER root
 

README.md

@@ -19,6 +19,7 @@ Here are some quick links:
 
 1. **Enhanced Profile Selection** - Better looking UI for KubeSpawner's `profileList` with rich descriptions
 2. **Dynamic Image Building** - Optional integration with BinderHub to build images on-demand
+3. **Permalinks and Auto-Start** - Automatically start pre-defined environments via permalinks.
 
 See the [User Guide](./docs/guide.md) for more details.
 

docs/guide.md

@@ -12,6 +12,8 @@ The package interprets your existing KubeSpawner `profile_list` configuration an
 - Better looking and more featureful interface
 - Descriptions for various options
 - Better descriptions for "write-in" choices
+- Permalink generation for pre-selected profile configurations
+- Auto-Start via Permalink Feature
 
 You configure profiles the same way as standard KubeSpawner—`jupyterhub-fancy-profiles` provides the enhanced UI!
 

docs/index.md

@@ -34,7 +34,11 @@ When enabled, integrates with BinderHub (deployed as a JupyterHub service) to al
 :::
 
 :::{card} ⚙️ Standard KubeSpawner config
-Works with your existing KubeSpawner configuration—no need to change how you define profiles.
+Works with your existing KubeSpawner configuration, no need to change how you define profiles.
+:::
+
+:::{card} 🔗 Auto-start permalinks
+Generate shareable URLs that automatically launch servers with pre-configured options, perfect for workshops, courses, or shared environments.
 :::
 
 ::::
@@ -85,6 +89,96 @@ View source and report issues
 
 ---
 
+## Auto-start feature
+
+The auto-start feature allows you to create shareable URLs that automatically launch a JupyterHub server with pre-configured settings. This is particularly useful for:
+
+- **Workshops and tutorials**: Provide participants with a link that starts their environment with the exact configuration needed
+- **Course materials**: Embed links in course content that launch students directly into the right environment
+- **Shared environments**: Create standardized setups for teams or projects
+
+### How it works
+
+1. Configure your desired server options in the profile form (profile type, image, resources, etc.)
+2. Click the "Copy Link" button to copy a permalink to your clipboard
+3. The copied URL includes `autoStart=false` by default, change this to `autoStart=true` in the URL to enable automatic launching
+4. Share the URL with others or bookmark it for yourself
+
+When someone visits a URL with `autoStart=true`, the form will automatically populate with the saved configuration and submit itself after a brief timeout, launching the server immediately.
+
+```{tip}
+The permalink button automatically sets `autoStart=false` to make it easy to create auto-start URLs. Simply change `false` to `true` in the copied URL to enable the auto-start behavior.
+```
+
+### Advanced: Combining with nbgitpuller URLs
+
+If your JupyterHub environment has [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) installed, you can combine auto-start permalinks with git-pull functionality to create URLs that both clone a repository and launch a pre-configured server. The nbgitpuller extension enables the `/hub/user-redirect/git-pull` URLs and automatically handles login redirects.
+
+This is especially useful for distributing workshop materials or course notebooks where you want participants to have both the right environment and the right content.
+
+Here's a Python script that generates such URLs:
+
+```python
+import urllib.parse
+import re
+
+# Configuration
+notebook_url = "https://github.com/org/repo/blob/branch/notebooks/example.ipynb"
+permalink = ""  # Permalink copied from fancy profiles form
+jupyterhub_url = "https://jupyterhub.example.org"
+
+# Extract repository information from notebook URL
+git_repo_url = notebook_url.split("/blob/")[0]
+branch = notebook_url.split("/blob/")[1].split("/")[0]
+notebook_path = "/".join(notebook_url.split("/blob/")[1].split("/")[1:])
+notebook_suburl = git_repo_url.split("/")[-1] + "/" + notebook_path
+
+# Build git-pull URL (requires nbgitpuller)
+gitpull_next = (
+    f"/hub/user-redirect/git-pull"
+    f"?repo={git_repo_url}"
+    f"&branch={branch}"
+    f"&urlpath=lab/tree/{notebook_suburl}"
+)
+
+# Build spawn URL with git-pull as next parameter
+spawn_next = "/hub/spawn?next=" + urllib.parse.quote(gitpull_next, safe="")
+
+# Extract fancy-forms-config from permalink and enable auto-start
+config_match = re.search(r"%23.+?(?=%7D)", permalink)
+if config_match:
+    fancy_forms_config = config_match[0].replace(
+        "%22autoStart%22%3A%22false%22",
+        "%22autoStart%22%3A%22true%22"
+    )
+    # Construct final URL
+    final_url = (
+        f"{jupyterhub_url}/hub/login"
+        f"?next={urllib.parse.quote(spawn_next, safe='')}"
+        f"{fancy_forms_config}%7D"
+    )
+    print(final_url)
+else:
+    print("Error: Could not extract config from permalink")
+```
+
+**How it works:**
+
+1. The script extracts the git repository URL and branch from a GitHub notebook URL
+2. It creates a git-pull URL that clones the repository and opens the specified notebook (enabled by nbgitpuller)
+3. It combines this with the fancy profiles configuration from your permalink
+4. It sets `autoStart=true` to automatically launch the server
+5. The nbgitpuller extension handles the login redirect flow automatically
+6. The result is a single URL that authenticates users, clones the repository, configures the server environment, and launches it automatically
+
+```{note}
+This requires [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) to be installed in your JupyterHub environment. nbgitpuller provides the `/hub/user-redirect/git-pull` endpoint and handles the authentication redirect flow.
+```
+
+**Example use case:** Share a link with workshop participants that gives them the right computational environment and opens the workshop notebook automatically.
+
+---
+
 ## Compatibility
 
 ```{note}

setupTests.js

@@ -4,6 +4,10 @@ import fetchMock from "jest-fetch-mock";
 fetchMock.enableMocks();
 
 HTMLCanvasElement.prototype.getContext = () => {};
+
+// Mock window.scrollTo
+window.scrollTo = jest.fn();
+
 Object.defineProperty(window, "matchMedia", {
   writable: true,
   value: jest.fn().mockImplementation((query) => ({

src/ImageBuilder.test.tsx

@@ -8,7 +8,11 @@ import renderWithContext from "./test/renderWithContext";
 test("select repository by org/repo", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -33,7 +37,11 @@ test("select repository by org/repo", async () => {
 test("select repository by https://github.com/org/repo", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -58,7 +66,11 @@ test("select repository by https://github.com/org/repo", async () => {
 test("select repository by https://www.github.com/org/repo", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -83,7 +95,11 @@ test("select repository by https://www.github.com/org/repo", async () => {
 test("select repository by github.com/org/repo", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -108,7 +124,11 @@ test("select repository by github.com/org/repo", async () => {
 test("select repository by www.github.com/org/repo", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -132,7 +152,11 @@ test("select repository by www.github.com/org/repo", async () => {
 test("invalid org/repo string (not matching pattern)", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -148,16 +172,16 @@ test("invalid org/repo string (not matching pattern)", async () => {
   await user.click(document.body);
 
   expect(
-    screen.getByText(
+    screen.getAllByText(
       "Provide the repository as the format 'organization/repository'.",
-    ),
-  );
+    ).length,
+  ).toBeGreaterThan(0);
 });
 
 test("repofield trims leading/trailing spaces", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(<form><ProfileForm /></form>);
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -171,15 +195,15 @@ test("repofield trims leading/trailing spaces", async () => {
   const repoField = screen.getByLabelText("Repository");
   await user.type(repoField, "     extra/spaces  ");
   await user.click(document.body);
-  await user.click(screen.getByRole("button", { name: "Build image" }));
+  await user.click(screen.getByRole("button", { name: "Build Image and Start" }));
 
   expect(repoField).toHaveValue("extra/spaces");
 });
 
 test("ref trims leading/trailing spaces", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(<form><ProfileForm /></form>);
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -194,15 +218,19 @@ test("ref trims leading/trailing spaces", async () => {
   await user.clear(refField);
   await user.type(refField, " branch ");
   await user.click(document.body);
-  await user.click(screen.getByRole("button", { name: "Build image" }));
+  await user.click(screen.getByRole("button", { name: "Build Image and Start" }));
 
   expect(refField).toHaveValue("branch");
 });
 
 test("invalid org/repo string (wrong base URL)", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -218,16 +246,20 @@ test("invalid org/repo string (wrong base URL)", async () => {
   await user.click(document.body);
 
   expect(
-    screen.getByText(
+    screen.getAllByText(
       "Provide the repository as the format 'organization/repository'.",
-    ),
-  );
+    ).length,
+  ).toBeGreaterThan(0);
 });
 
 test("no org/repo provided", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -237,19 +269,23 @@ test("no org/repo provided", async () => {
   await user.click(select);
 
   await user.click(screen.getByText("Build your own image"));
-  await user.click(screen.getByRole("button", { name: "Build image" }));
+  await user.click(screen.getByRole("button", { name: "Build Image and Start" }));
 
   expect(
-    screen.getByText(
+    screen.getAllByText(
       "Provide the repository as the format 'organization/repository'.",
-    ),
-  );
+    ).length,
+  ).toBeGreaterThan(0);
 });
 
 test("no branch selected", async () => {
   const user = userEvent.setup();
 
-  renderWithContext(<ProfileForm />);
+  renderWithContext(
+    <form>
+      <ProfileForm />
+    </form>
+  );
   const radio = screen.getByRole("radio", {
     name: "CPU only No GPU, only CPU",
   });
@@ -265,7 +301,7 @@ test("no branch selected", async () => {
   await user.click(document.body);
 
   await user.clear(screen.queryByLabelText("Git Ref"));
-  await user.click(screen.getByRole("button", { name: "Build image" }));
+  await user.click(screen.getByRole("button", { name: "Build Image and Start" }));
 
-  expect(screen.getByText("Enter a git ref."));
+  expect(screen.getAllByText("Enter a git ref.").length).toBeGreaterThan(0);
 });