Bun Installation

BugPin can be installed and run directly with the Bun runtime without Docker. This is the recommended approach for Linux servers where you want full control of the process, lower container overhead, or integration with systemd for automatic startup and log management.

Prerequisites

Bun v1.1 or later
Git (to clone the repository)
CPU: 1 core minimum (2 cores recommended for production)
RAM: 512MB minimum, 1GB recommended for production. If building on the same machine, 1GB is required as the build step (bun run build) compiles the Admin Console and widget.
Disk: 1GB minimum for the application and dependencies; additional space depends on screenshot and attachment volume (plan for 10–50MB per 1,000 reports)
Linux, macOS, or Windows (Linux recommended for production)

Installation

1. Clone the Repository

git clone https://github.com/aranticlabs/bugpin.git
cd bugpin

2. Install Dependencies

bun install

3. Build for Production

bun run build

This builds:

Server (TypeScript compilation)
Admin Console (React/Vite build)
Widget (Preact/Vite build)

4. Start the Server

bun run start

BugPin is now running at http://localhost:7300.

Open http://localhost:7300 and login with:

Email: admin@example.com
Password: changeme123

warning

Change the default password immediately after first login in Settings → Users.

Development Mode

For development with hot reload:

# Start both server and admin with hot reload
bun run dev

This runs:

Server on port 7301 with hot reload
Admin Console on port 7300 with Vite HMR

Access the admin at http://localhost:7300/admin.

Or start components separately:

bun run dev:server   # Server with hot reload (port 7301)
bun run dev:admin    # Admin Console with Vite HMR (port 7300)
bun run dev:widget   # Widget with watch mode

Available Commands

Command	Description
`bun run dev`	Start development servers (server + admin)
`bun run build`	Build all components for production
`bun run start`	Start production server
`bun run typecheck`	Run TypeScript type checking
`bun run test`	Run tests
`bun run migrate`	Run database migrations

Data Directory

BugPin stores data in the ./data directory (relative to where you run BugPin):

data/
├── bugpin.db      # SQLite database
├── .secret        # Auto-generated session key
└── uploads/       # Uploaded screenshots and attachments

Running as a Service

For production deployments, run BugPin as a systemd service. See the systemd guide for detailed instructions.

Quick start:

# Copy the service file
sudo cp bugpin.service /etc/systemd/system/

# Edit paths if needed
sudo nano /etc/systemd/system/bugpin.service

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable bugpin
sudo systemctl start bugpin

Updating

# Pull latest changes
git pull origin main

# Install any new dependencies
bun install

# Rebuild
bun run build

# Restart the server
sudo systemctl restart bugpin  # if using systemd

Reverse Proxy

For production, place BugPin behind a reverse proxy. See the Docker installation guide for Nginx and Traefik examples.

Should You Use Bun or Docker?

Aspect	Bun	Docker
Setup complexity	More steps	Simpler
Resource usage	Lower overhead	Container overhead
Updates	Git pull + rebuild	Docker pull
Isolation	Shared system	Containerized
Best for	Development, custom setups	Production, simplicity

Prerequisites​

Installation​

1. Clone the Repository​

2. Install Dependencies​

3. Build for Production​

4. Start the Server​

5. Login and Change Password​

Development Mode​

Available Commands​

Data Directory​

Running as a Service​

Updating​

Reverse Proxy​

Should You Use Bun or Docker?​

Next Steps​