Skip to content

Quick Start

Get Issue Log Workbench running locally in a few minutes.

Prerequisites

  • Python 3.11 or newer (python --version)
  • pip (bundled with Python)
  • A terminal / command prompt

Step-by-Step

1. Clone the repository

git clone https://github.com/mattbriggs/issue-log-workbench.git
cd issue-log-workbench

If you already have a local checkout, just cd into it and continue.

2. Create a virtual environment

python -m venv .venv

Activate it:

source .venv/bin/activate

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

3. Install the package

pip install -e ".[dev]"

This installs the workbench in editable mode along with development tools such as pytest, ruff, and MkDocs.

4. Initialise the database

workbench init-db

This creates the local data directory, SQLite database, and attachments folder under ~/.issue_workbench/ by default.

5. Start the server

workbench serve

You should see output like:

Starting Issue Log Workbench on http://127.0.0.1:8000
INFO:     Uvicorn running on http://127.0.0.1:8000

6. Open the app

Open http://127.0.0.1:8000 in your browser. You will see the empty issue list.

Optional Database Commands

workbench db status
workbench db upgrade
workbench db backup

Use these when you want to inspect migration state, apply pending migrations, or back up your local database.

Common CLI Options

workbench serve --port 9000          # use a different port
workbench serve --reload             # auto-reload on code changes
workbench serve --host 0.0.0.0       # listen on all interfaces (caution!)
workbench init-db                    # re-run local setup

Configuration via Environment Variables

All settings can be overridden with WORKBENCH_* environment variables or a .env file in the project root:

WORKBENCH_PORT=9000
WORKBENCH_DEBUG=true
WORKBENCH_DATA_DIR=/tmp/my_workbench

Next Steps