Quick Start

Get BugPin up and running in under 2 minutes. This guide walks through the basic setup to start capturing and managing bug reports with the self-hosted visual feedback tool.

Prerequisites

• CPU: 1 core minimum
• RAM: 512MB minimum, 1GB recommended for production

Choose one of the following installation methods:

• Docker (recommended): Docker Engine 20.10+ and Docker Compose v2+
• Bun: Bun runtime v1.1 or later and Git

Step 1: Install BugPin Server

Using Docker (Recommended)

Option 1: Docker Compose (Easiest)

Create a docker-compose.yml file:

services:
  bugpin:
    image: registry.arantic.cloud/bugpin/bugpin:latest
    container_name: bugpin
    restart: unless-stopped
    ports:
      - "7300:7300"
    volumes:
      - ./data:/data

Then run:

docker compose up -d

File Permissions

If you're using a bind mount (./data:/data), set ownership before starting:

mkdir -p data
sudo chown -R 1000:1000 data
docker compose up -d

Without this, the container may crash with a permission error. See FAQ if you hit this issue.

Option 2: Docker Run

docker run -d \
  --name bugpin \
  --restart unless-stopped \
  -p 7300:7300 \
  -v bugpin-data:/data \
  registry.arantic.cloud/bugpin/bugpin:latest

BugPin will be available at http://localhost:7300

For detailed installation instructions, see:

• Docker Installation
• Bun Installation

The login screen will appear:

Step 2: First Login

Log in with the default credentials:

• Email: admin@example.com
• Password: changeme123

After logging in, you'll see the admin dashboard:

Important: Change the default password immediately after first login:

1. Click your profile icon in the top right
2. Select "Account Settings"
3. Update your password

Step 3: Create Your First Project

Projects organize bug reports and provide API keys for widget integration.

1. Navigate to Projects in the sidebar
2. Click Create Project
3. Enter a project name (e.g., "My Website")
4. Click Create

After creation, you'll see your API Key. Copy this key - you'll need it for the widget installation.

Step 4: Add Widget to Your Site

Add the BugPin widget to your website by including this script tag before the closing </body> tag:

<script
  src="http://localhost:7300/widget.js"
  data-api-key="YOUR_API_KEY_HERE"
  async
></script>

Replace YOUR_API_KEY_HERE with the API key from Step 3.

For production deployment, replace http://localhost:7300 with your actual BugPin server URL (e.g., https://bugpin.example.com).

For advanced widget configuration, see Widget Installation.

Step 5: Test the Widget

1. Open your website in a browser
2. Look for the BugPin button (default: bottom-right corner)
3. Click the button to open the widget
4. Take a screenshot and add annotations
5. Submit your first bug report

Check your BugPin admin panel - you should see the report in the Reports section!

Next Steps

Now that BugPin is running, explore these features:

Configuration

• Server Configuration - Configure SMTP, security, and environment settings
• Widget Settings - Customize widget appearance and behavior
• Branding - Add your logo and customize colors
• User Management - Invite team members with different roles

Production Deployment

• Reverse Proxy Setup - Deploy with Traefik, Nginx, Caddy, or Apache

Integrations

• GitHub Integration - Create GitHub issues from bug reports

Advanced

• Widget Annotation Tools - Learn about all annotation capabilities
• API Reference - Build custom integrations
• Monitoring - Set up logging and monitoring

Having Issues?

Check the FAQ for answers to common questions:

• Widget not appearing or not sending reports
• Cannot access admin panel
• Authentication issues
• Integration problems
• And more...

Need Help?

• FAQ: Common questions and answers
• Documentation: Browse the full documentation in the sidebar
• GitHub Issues: Report bugs or request features
• License: Server/Admin is AGPL-3.0, Widget is MIT licensed

---

Congratulations! You've successfully set up BugPin. Start capturing bug reports and streamline your development workflow.