From 189c3589753209b38caf7b67d8772b08bb9190fd Mon Sep 17 00:00:00 2001
From: Thomas Eizinger <thomas@eizinger.io>
Date: Tue, 11 Nov 2025 13:18:33 +1100
Subject: [PATCH] feat(portal): add Debian/Ubuntu deployment tab (#10741)

Now that we have an APT repository for Debian / Ubuntu packages, we
should also tell our users about it. We introduce a new "Debian /
Ubuntu" tab on the deployments screen in the portal. The tab is selected
by default as it should provide the best user experience for manually
deployed Gateways:

- Updates are as easy as `sudo apt upgrade`
- The systemd file and token are fully managed in the background

Here is what the new tab looks like:

<img width="679" height="786" alt="image"
src="https://github.com/user-attachments/assets/da69fc55-6a6a-476d-bed4-634dd05df8bc"
/>


Resolves: #10701

---------

Signed-off-by: Thomas Eizinger <thomas@eizinger.io>
Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
---
 .../apps/web/lib/web/live/sites/new_token.ex  | 78 ++++++++++++++++++-
 .../app/kb/administer/upgrading/readme.mdx    | 13 +++-
 2 files changed, 89 insertions(+), 2 deletions(-)

diff --git a/elixir/apps/web/lib/web/live/sites/new_token.ex b/elixir/apps/web/lib/web/live/sites/new_token.ex
index b4e4913f4..47760d139 100644
--- a/elixir/apps/web/lib/web/live/sites/new_token.ex
+++ b/elixir/apps/web/lib/web/live/sites/new_token.ex
@@ -31,7 +31,7 @@ defmodule Web.Sites.NewToken do
     {:noreply,
      assign(socket,
        uri: uri,
-       selected_tab: Map.get(params, "method", "systemd-instructions")
+       selected_tab: Map.get(params, "method", "debian-instructions")
      )}
   end
 
@@ -68,6 +68,61 @@ defmodule Web.Sites.NewToken do
           </div>
 
           <.tabs :if={@env} id="deployment-instructions">
+            <:tab
+              id="debian-instructions"
+              icon="os-debian"
+              label="Debian / Ubuntu"
+              phx_click="tab_selected"
+              selected={@selected_tab == "debian-instructions"}
+            >
+              <p class="p-6">
+                Step 1: Add the Firezone package repository.
+              </p>
+
+              <.code_block
+                id="code-sample-debian1"
+                class="w-full text-xs whitespace-pre-line"
+                phx-no-format
+                phx-update="ignore"
+              ><%= debian_command_apt_repository() %></.code_block>
+
+              <p class="p-6">
+                Step 2: Install the Gateway:
+              </p>
+
+              <.code_block
+                id="code-sample-debian2"
+                class="w-full text-xs whitespace-pre-line"
+                phx-no-format
+                phx-update="ignore"
+              ><%= debian_command_install() %></.code_block>
+
+              <p class="p-6">
+                Step 3: Copy the token:
+              </p>
+
+              <.code_block
+                id="code-sample-debian3"
+                class="w-full text-xs whitespace-pre-line"
+                phx-no-format
+                phx-update="ignore"
+              ><%= token(@env) %></.code_block>
+
+              <p class="p-6">
+                Step 4: Configure the token:
+              </p>
+
+              <.code_block
+                id="code-sample-debian4"
+                class="w-full text-xs whitespace-pre-line"
+                phx-no-format
+                phx-update="ignore"
+              ><%= debian_command_authenticate() %></.code_block>
+
+              <p class="p-6">
+                Step 5: You are now ready to manage the Gateway using the <code>firezone</code> CLI.
+              </p>
+            </:tab>
             <:tab
               id="systemd-instructions"
               icon="hero-command-line"
@@ -255,6 +310,27 @@ defmodule Web.Sites.NewToken do
     value
   end
 
+  defp debian_command_apt_repository do
+    """
+    mkdir --parents /etc/apt/keyrings
+    wget -qO- https://artifacts.firezone.dev/apt/key.gpg | gpg --dearmor -o /etc/apt/keyrings/firezone.gpg
+    echo "deb [signed-by=/etc/apt/keyrings/firezone.gpg] https://artifacts.firezone.dev/apt/ stable main" > /etc/apt/sources.list.d/firezone.list
+    """
+  end
+
+  defp debian_command_install do
+    """
+    apt update
+    apt install firezone-gateway
+    """
+  end
+
+  defp debian_command_authenticate do
+    """
+    firezone gateway authenticate
+    """
+  end
+
   defp docker_command(env) do
     [
       "docker run -d",
diff --git a/website/src/app/kb/administer/upgrading/readme.mdx b/website/src/app/kb/administer/upgrading/readme.mdx
index 1ff06758d..eab25aa29 100644
--- a/website/src/app/kb/administer/upgrading/readme.mdx
+++ b/website/src/app/kb/administer/upgrading/readme.mdx
@@ -47,7 +47,18 @@ image with the newer version and then restarting. See below for specific steps
 depending on how you've deployed your Gateway:
 
 <TabsGroup>
-<TabsItem title="Docker" active>
+<TabsItem title="APT repository" active>
+
+If you installed the Gateway from the `artifacts.firezone.dev` APT repository,
+you can upgrade the Gateway via `apt`:
+
+```bash
+sudo apt update
+sudo apt upgrade firezone-gateway
+```
+
+</TabsItem>
+<TabsItem title="Docker">
 
 Copy-paste the following command to upgrade your Docker-based Gateway: