Server Configuration

BugPin is designed for simplicity. All server settings are configured through the Admin Console after installation, with no environment variables required for typical deployments. This page covers the default configuration, data storage layout, the health check endpoint, and performance tuning options.

Default Setup

BugPin works out of the box with sensible defaults:

• Admin account: admin@example.com / changeme123
• Session key: Auto-generated on first run
• Port: 7300
• Database: SQLite in data volume

Change Default Password

After first login, immediately change the default admin password in Users.

Admin Console Navigation

The Admin Console sidebar is split into three groups:

• Workspace — Dashboard, Reports, Projects
• Widget — Button, Dialog, Screenshot, Language (instance-wide widget defaults)
• Console — Settings, Notifications, Users, Security, Branding, License

URLs are flat and predictable: /settings, /notifications, /users, /security, /branding, /license, /button, /dialog, /screenshot, /language.

Admin Console Settings

All configuration is done in the Admin Console:

Setting	Location	Description
General (app URL, retention)	Settings → General	Core server settings
Storage (local / S3)	Settings → Storage	Upload backend
SMTP	Settings → SMTP	Email sender configuration
Team notifications	Notifications → General	Default recipients for team-facing emails
Reporter notifications	Notifications → Reporter	Confirmation, status, priority, assignment emails
Email templates	Notifications → Email Templates	Customize reporter and team email bodies
Rate limiting	Security	Requests per minute
Session duration	Security	Login session length
Domain whitelist	Projects → Select project → Settings	Allowed widget domains (per project)
Widget appearance	Widget → Button / Dialog / Screenshot	Button style, colors, capture settings
Widget language	Widget → Language	Auto / Manual locale
Branding	Branding	Logo, colors, favicon
User management	Users	Add/manage users
License	License	Enterprise license key

Project-Level Settings

Each project can have its own configuration:

Setting	Location	Description
Whitelisted domains	Project → Settings	Allowed widget domains
GitHub integration	Project → Integrations	Issue sync

Data Storage

BugPin stores all data in the /data directory inside the container (Docker) or ./data locally (Bun).

Docker

Mount a volume to persist data:

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

Systemd / Bun

Data is stored in ./data relative to where you run BugPin.

Data Directory Structure

The data directory contains:

data/
├── bugpin.db          # SQLite database
├── .secret            # Auto-generated session key
└── uploads/
    ├── screenshots/   # Bug report screenshots
    ├── attachments/   # File attachments
    └── branding/      # Custom logos/icons

tip

For most deployments, just use the default docker-compose.yml and configure everything in the Admin Console after installation.

Health Checks

The BugPin server provides a health check endpoint:

curl https://bugpin.example.com/health

Response:

{
  "success": true,
  "status": "healthy",
  "timestamp": "2024-01-06T12:00:00.000Z",
  "version": "1.0.0"
}

Use this endpoint for:

• Docker health checks
• Load balancer health checks
• Monitoring systems

Performance Tuning

Widget Script Caching

The widget script has a 1-hour cache:

Cache-Control: public, max-age=3600

This reduces server load while allowing updates to propagate within an hour.

Database Location

For better performance, consider:

• Using SSD storage for the /data volume
• Regular database backups
• Monitoring database size

Resource Limits

Recommended Docker resource limits:

services:
  bugpin:
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.5"
          memory: 256M

Monitoring

See Monitoring & Logging for detailed monitoring configuration.