Skip to content

docs: beginner installation guide (.deb, udev, dependencies) #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tech-stack-studios merged 1 commit into from
May 27, 2026
Merged

docs: beginner installation guide (.deb, udev, dependencies) #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,14 @@ The Scene, Scene Collection, Source, Input, and Transition pickers in the Proper

## Installation

### Installing from the pre-built package (recommended)

Download the latest `.deb` from the [Releases page](https://github.com/FritzBlignaut/tech-stack-streamdeck/releases) and follow the step-by-step guide:

📖 **[Installation Guide](docs/installation-guide.md)** — covers dependency setup, `.deb` install, udev rules, and first-launch verification.

### Building from source (developers)

```bash
# 1. Clone the repo
git clone https://github.com/your-username/tech-stack-streamdeck.git
Expand Down
270 changes: 270 additions & 0 deletions docs/installation-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,270 @@
# Tech Stack Stream Deck — Installation Guide

> **Platform:** Linux only (Ubuntu 24.04 / Linux Mint 22.x or compatible Ubuntu-based distros)
> **Hardware:** Elgato Stream Deck (tested on Original V2)
> **Install method:** Pre-built `.deb` package — no programming knowledge required

This guide walks you through installing the Tech Stack Stream Deck application from the downloadable `.deb` package, setting up all the tools it needs to work, and verifying that your Stream Deck is recognised.

---

## Before You Start

Make sure you have the following ready:

- [ ] Your Elgato Stream Deck plugged in via USB
- [ ] A working internet connection (to download the package and install tools)
- [ ] Ubuntu 24.04, Linux Mint 22.x, or a compatible Ubuntu-based distro
- [ ] Access to a terminal — press **Ctrl + Alt + T** to open one

> **Not sure which distro you have?** Open a terminal and run `lsb_release -d`. The output will say something like `Ubuntu 24.04.1 LTS` or `Linux Mint 22.3`.

---

## Step 1 — Install Required Tools

The application relies on a handful of command-line tools that handle hotkeys, media control, and volume. These need to be installed **before** you launch the app for the first time — otherwise those button types will silently do nothing.

Open a terminal (**Ctrl + Alt + T**) and run:

```bash
sudo apt install xdotool playerctl pulseaudio-utils
```

**What this does:**
- `sudo` — runs the command with administrator privileges (you will be asked for your password)
- `apt install` — downloads and installs the listed packages from Ubuntu's software servers
- `xdotool` — lets the app simulate keyboard shortcuts on your computer (used by Hotkey buttons)
- `playerctl` — lets the app control music and video players like Spotify, VLC, and Firefox (used by Media Control buttons)
- `pulseaudio-utils` — provides `pactl`, the tool that adjusts your system volume (used by Volume buttons)

> **Note:** `xdg-open` and `gtk-launch` (used for Open URL and Open Application buttons) are already included in standard Ubuntu/Mint desktop installations — you don't need to install them separately.

After the installation finishes, you can verify the tools are available by running:

```bash
xdotool --version
playerctl --version
pactl --version
```

Each command should print a version number. If any of them prints `command not found`, re-run the `apt install` command above.

> [Screenshot: terminal showing the `apt install` command running and completing with "0 upgraded, 3 newly installed"]

---

## Step 2 — Download the `.deb` Package

1. Open your web browser and go to the **Releases** page:
**https://github.com/FritzBlignaut/tech-stack-streamdeck/releases**

2. Click on the **latest release** (at the top of the list).

3. Scroll down to the **Assets** section and click the file ending in `_amd64.deb` to download it.
The filename will look something like `tech-stack-streamdeck_0.0.1_amd64.deb`.

> [Screenshot: GitHub Releases page with the latest release expanded, showing the Assets section and the .deb file highlighted]

4. Your browser will save the file to your **Downloads** folder (`~/Downloads`).

> [Screenshot: file manager showing the downloaded .deb file in the Downloads folder]

---

## Step 3 — Install the Package

You can install the `.deb` file either through the graphical interface or the terminal. Choose whichever feels more comfortable.

### Method A — Graphical (recommended for beginners)

1. Open your **Files** app (file manager).
2. Navigate to your **Downloads** folder.
3. **Double-click** the `.deb` file.
4. The **Software Manager** (or GDebi) will open, showing the application name and description.
5. Click **Install**, then enter your password when prompted.
6. Wait for the progress bar to complete. The application is now installed.

> [Screenshot: Software Manager showing the Tech Stack Stream Deck package with the Install button]

### Method B — Terminal

Open a terminal and run:

```bash
cd ~/Downloads
sudo dpkg -i tech-stack-streamdeck_*.deb
```

**What this does:**
- `cd ~/Downloads` — moves you into your Downloads folder where the file was saved
- `sudo dpkg -i` — installs the `.deb` package with administrator privileges
- The `*` wildcard matches the filename automatically so you don't have to type the exact version number

> [Screenshot: terminal showing the output of `dpkg -i` completing successfully with "Setting up tech-stack-streamdeck"]

**If you see an error about missing dependencies**, run this to fix them automatically:

```bash
sudo apt-get install -f
```

This tells `apt` to find and install anything the package needs that isn't on your system yet.

---

## Step 4 — Grant USB Access to the Stream Deck (Required)

This is the most important step. By default, Linux does not allow regular applications to talk directly to USB devices for security reasons. You need to create a single configuration file (called a **udev rule**) that tells the system: *"This application is allowed to access Elgato hardware."*

**Without this step, the application will open but will not detect your Stream Deck.**

The entire process takes about two minutes.

### 4.1 — Create the rule file

In a terminal, run:

```bash
sudo nano /etc/udev/rules.d/50-elgato.rules
```

**What this does:**
- `sudo` — opens the file with administrator privileges so you can write to it
- `nano` — a simple text editor that runs inside the terminal
- `/etc/udev/rules.d/50-elgato.rules` — this is the file being created; the `50-` prefix tells udev to load it in a predictable order

The terminal will change to show the nano text editor with a blank file.

> [Screenshot: terminal showing the nano editor open with an empty file and the filename in the title bar]

### 4.2 — Type the rule

Type (or paste) the following line exactly as shown — spacing and quotation marks matter:

```
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0fd9", TAG+="uaccess"
```

**What this means:**
- `SUBSYSTEM=="hidraw"` — applies to raw HID USB devices
- `ATTRS{idVendor}=="0fd9"` — matches only Elgato hardware (their vendor ID is `0fd9`)
- `TAG+="uaccess"` — grants access to the currently logged-in user automatically, without needing `sudo` every time

> [Screenshot: nano editor showing the rule line typed in the file]

### 4.3 — Save and exit

1. Press **Ctrl + O** — this saves the file (nano will ask you to confirm the filename; just press **Enter**)
2. Press **Ctrl + X** — this closes the editor and returns you to the normal terminal

### 4.4 — Apply the rule and replug

Tell the system to reload its device rules:

```bash
sudo udevadm control --reload-rules
sudo udevadm trigger
```

Then **unplug your Stream Deck from the USB port and plug it back in**. This causes the system to apply the new rule to the device.

> [Screenshot: Stream Deck cable being plugged into a USB port]

---

## Step 5 — Launch the App and Verify

### Finding the app

After installation, **Tech Stack Stream Deck** will appear in your application menu. Search for it by name:

- **Linux Mint / Cinnamon:** press the **Start** menu button → type `Tech Stack`
- **GNOME:** press the **Super** key → type `Tech Stack`
- **XFCE:** Applications menu → search for `Tech Stack`

> [Screenshot: application launcher showing "Tech Stack Stream Deck" in the search results]

Click the icon to launch it.

### What a successful launch looks like

When your Stream Deck is connected and the udev rule is applied correctly, the application will:

- Show your Stream Deck button grid in the centre of the window
- Display a **green connected indicator** in the top-right corner
- Light up the actual buttons on your Stream Deck hardware

> [Screenshot: Tech Stack Stream Deck application window showing the button grid with the device connected — green indicator visible]

### If the app says "No devices found"

This means either:
- The udev rule wasn't saved correctly — check [Step 4](#step-4--grant-usb-access-to-the-stream-deck-required) and run `cat /etc/udev/rules.d/50-elgato.rules` to verify the file contains the rule
- The device wasn't replugged after the rule was loaded — unplug and replug the Stream Deck
- You are using a Stream Deck model other than the Original V2 (other models may work but are untested)

> [Screenshot: app showing "No devices found" state (disconnected indicator) for comparison]

---

## Step 6 — Configure Your Buttons (Quick Start)

Now that the app is running and your device is connected, here's a quick overview of what works out of the box:

| Button type | Status | Requires |
|---|---|---|
| **Hotkey** | ✅ Ready | `xdotool` (installed in Step 1) |
| **Open URL** | ✅ Ready | `xdg-open` (pre-installed) |
| **Open Application** | ✅ Ready | `gtk-launch` (pre-installed) |
| **Run Command** | ✅ Ready | `bash` (pre-installed) |
| **Volume (raise/lower/mute)** | ✅ Ready | `pactl` (installed in Step 1) |
| **Media Control** | ✅ Ready* | `playerctl` (installed in Step 1) |
| **Clock / Date display** | ✅ Ready | — |
| **CPU / RAM display** | ✅ Ready | — |

> *Media Control requires a running media player with MPRIS support (Spotify, VLC, Firefox, Rhythmbox, etc.).
> To check that your player is visible, run `playerctl -l` in a terminal — it should list your player by name.

### Closing the app

Clicking the **window's × button** hides the app to the system tray — it keeps running in the background so your button actions still work. To fully quit, **right-click the tray icon** and choose **Quit**.

---

## Optional — Launch on Login

If you want the app to start automatically when you log in:

- **Linux Mint / Cinnamon:** System Settings → **Startup Applications** → Add → command: `tech-stack-streamdeck`
- **GNOME:** Install the **GNOME Tweaks** extension or use **Startup Applications** if available
- **XFCE:** Settings → **Session and Startup** → Application Autostart → Add

> [Screenshot: Startup Applications dialog with Tech Stack Stream Deck added as a startup entry]

---

## Troubleshooting

| Symptom | Most likely cause | Fix |
|---|---|---|
| App opens but shows "No devices found" | udev rule missing or device not replugged | Re-do [Step 4](#step-4--grant-usb-access-to-the-stream-deck-required), then unplug and replug the Stream Deck |
| Hotkey buttons do nothing | `xdotool` not installed | `sudo apt install xdotool` |
| Media control buttons do nothing | `playerctl` not installed, or player has no MPRIS | `sudo apt install playerctl`, then run `playerctl -l` to check your player |
| Volume buttons do nothing | `pactl` not installed | `sudo apt install pulseaudio-utils` |
| "dependency not met" error during install | apt package list is outdated | `sudo apt update` then retry the install |
| App won't launch at all after install | `libudev1` runtime missing | `sudo apt install libudev1` |
| App was working, now shows "No devices found" after a system update | udev rules were cleared | Re-do [Step 4.4](#44--apply-the-rule-and-replug) (`udevadm reload` + replug) |
| Window disappears when I click × | This is intentional — app hides to tray | Right-click the tray icon → **Quit** |

---

## Next Steps

- **Install plugins** (OBS Studio, Discord Push-to-Talk) — see the separate Plugin Installation Guide *(coming soon)*
- **Create profiles** — use the profile switcher at the top of the app to create named layouts for different workflows
- **Icon Library** — assign images to your buttons by pointing the app at a local folder of `.png` / `.gif` files via the button editor panel

---

*For more information, visit the [project repository](https://github.com/FritzBlignaut/tech-stack-streamdeck).*