Skip to content

Launching as a macOS App

If you want to start Issue Log Workbench like a normal macOS app, you can wrap the local server in an Automator application that runs a small shell script.

This approach is useful when you want:

  • A double-clickable app in Finder
  • A Dock icon or Applications entry
  • A repeatable way to start the local server and open the browser

Prerequisites

  • A working local checkout of this repository
  • A created virtual environment in the repo
  • Dependencies already installed
  • workbench serve working from Terminal

Test that first:

cd /Volumes/Matt_files/Git/mb/issue-log-workbench
source .venv/bin/activate
workbench serve

If that does not work in Terminal yet, fix that before setting up Automator.

Step 1. Create a Launcher Script

Create a shell script somewhere stable, for example:

~/Applications/Issue Log Workbench/run-workbench.sh

Example script:

#!/bin/bash
set -euo pipefail

REPO="/Volumes/Matt_files/Git/mb/issue-log-workbench"
LOG_DIR="$HOME/Library/Logs"
LOG_FILE="$LOG_DIR/issue-log-workbench.log"
URL="http://127.0.0.1:8000"

mkdir -p "$LOG_DIR"
cd "$REPO"

if ! curl -fsS "$URL/" >/dev/null 2>&1; then
  source "$REPO/.venv/bin/activate"
  nohup "$REPO/.venv/bin/workbench" serve >>"$LOG_FILE" 2>&1 &
  sleep 2
fi

open "$URL/"

Make it executable:

chmod +x "$HOME/Applications/Issue Log Workbench/run-workbench.sh"

Step 2. Test the Script

Run it directly:

"$HOME/Applications/Issue Log Workbench/run-workbench.sh"

Expected result:

  • The server starts if it is not already running
  • Your browser opens to http://127.0.0.1:8000
  • Logs are written to ~/Library/Logs/issue-log-workbench.log

Step 3. Create the Automator App

  1. Open Automator.
  2. Choose Application as the document type.
  3. Add the Run Shell Script action.
  4. Set:
  5. Shell: /bin/bash
  6. Pass input: to stdin
  7. Paste:
"$HOME/Applications/Issue Log Workbench/run-workbench.sh"
  1. Save the Automator application as Issue Log Workbench.app.
  2. Move it to /Applications or keep it wherever you prefer.

Now you can launch the workbench by double-clicking the app.

Optional Improvements

Add a Custom Icon

  1. Create or choose an image file.
  2. Open the saved app in Finder.
  3. Use Get Info and paste a copied icon onto the app icon in the info panel.

Use a Different Port

If you want a non-default port, change the script:

URL="http://127.0.0.1:9000"
nohup "$REPO/.venv/bin/workbench" serve --port 9000 >>"$LOG_FILE" 2>&1 &

Use a Different Data Directory

If you want the app to use a custom data location:

export WORKBENCH_DATA_DIR="$HOME/.issue_workbench_custom"

Add that line before the workbench serve command in the script.

Troubleshooting

The browser opens but the page does not load

  • Wait a few seconds and reload once
  • Check ~/Library/Logs/issue-log-workbench.log
  • Confirm the port is not already being used by another process

The app does nothing

  • Run the launcher script directly from Terminal
  • Confirm the repository path in the script is correct
  • Confirm .venv/bin/workbench exists
  • Confirm the script is executable

The app starts multiple servers

The example script checks the local URL before starting a new process. If you change the port, update both the URL value and the workbench serve command so they stay aligned.

  • Use Automator only as a launcher
  • Keep upgrades, backups, and debugging in Terminal
  • Re-test the launcher script after Python or dependency changes