Broke Documentation

Getting Started

Broke is a simple ticket and error tracking system. It's designed for small teams who need a straightforward way to manage issues and capture errors from their applications.

What you can do with Broke:

• Create and manage tickets with priorities, labels, and assignees
• Track errors from your applications (compatible with Sentry SDK)
• Organize work into projects
• Collaborate with your team

Features

Installation

Quick Start with Docker

1. Clone and start:

git clone https://github.com/valteryde/broke.git
cd broke
docker compose up -d

2. Create your admin account:

docker compose exec broke-server python cli.py create-user admin yourpassword admin@example.com --admin 1

3. Open Broke:

Go to http://localhost:8080 in your browser

Creating Users

First User (Admin)

After installation, create your first admin user via the command line:

docker compose exec broke-server python cli.py create-user <username> <password> <email> --admin 1

Inviting Team Members

Once logged in as an admin:

1. Go to Settings
2. Navigate to the Invites section
3. Create an invite link
4. Share the link with your team member

They can use the link to create their own account.

Projects

Projects help you organize your work. Each project can contain tickets and error tracking services.

Creating a Project

1. Go to the settings → Projects
2. Click New Project

Project Parts (Services)

Within each project, you can create "parts" — these represent different services or components of your application. Parts are used for error tracking, allowing you to separate errors by service. This can be found in the error page.

Tickets

Creating a Ticket

1. Navigate to a project
2. Click New Ticket
3. Fill in:
   • Title — A brief description of the issue
   • Description — Detailed information (supports rich text)
   • Priority — None, Low, Medium, High, or Urgent
   • Status — Backlog, Todo, In Progress, Done, or Closed
   • Labels — Add tags to categorize the ticket
   • Assignees — Assign team members

Managing Tickets

• Filter tickets by status, priority, or label using the filter options
• Search for tickets using the search bar
• Edit a ticket by clicking on it to open the detail view
• Close a ticket by changing its status to Done or Closed

Labels

Labels help categorize tickets. Create custom labels with colors to organize your work:

1. Go to Settings → Labels
2. Click Add Label
3. Enter a name and choose a color

Error Tracking

Broke can capture errors from your applications using the Sentry SDK.

Setup

1. Go to Settings → Sentry DSN
2. Click Generate Token to create a DSN token
3. Create a Project Part for your service (e.g., "Backend API", "Web App")
4. Copy your DSN URL

Connecting Your Application

Use the Sentry SDK in your application with your Broke DSN:

Python:

import sentry_sdk

sentry_sdk.init(
    dsn="http://your-token@your-server:8080/ingest/1",
)

JavaScript:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "http://your-token@your-server:8080/ingest/1",
});

Viewing Errors

• Errors appear in the Errors section of your project
• Similar errors are automatically grouped together
• Click on an error to see the full stack trace and details
• Create a ticket directly from an error to track the fix

Error Status

• Unresolved — New errors that need attention
• Resolved — Errors that have been fixed
• Ignored — Errors you've chosen to ignore

Importing from Linear

If you're migrating from Linear, you can import your existing data:

docker compose exec broke-server python cli.py import linear <your-linear-api-key>

To get your Linear API key:

1. Go to Linear Settings → Security
2. Create a new personal API key
3. Copy the key

What gets imported:

• Teams become Projects
• Issues become Tickets (with status, priority, and descriptions)
• Labels (with colors)
• Images are downloaded and stored locally

Settings

Access settings by clicking the gear icon or navigating to Settings.

Profile

Update your display name and profile information.

Security

• Change your password
• Manage your account security

Webhooks

Set up outgoing webhooks to notify external services when events occur in Broke. Useful for integrations with chat tools or other systems.

Danger Zone

Delete your account (this action cannot be undone).

Updating Broke

To update to the latest version:

./scripts/update.sh --dir /path/to/broke

The update script will:

1. Download the latest version
2. Preserve your data
3. Restart the server

Rollback

If you need to go back to a previous version, the update script keeps old versions. Simply stop the current container and start the previous one.

Tips

• Keyboard shortcuts — Press ? anywhere to see available shortcuts
• Quick search — Use the search bar to find tickets across all projects
• News feed — Check the dashboard to see recent activity across your team