Skip to main content

BugPin systemd Service

On Linux servers, BugPin can be run as a systemd service with automatic startup on boot, process supervision, and integrated log management via journalctl. This guide covers creating a dedicated system user, installing BugPin, configuring the service unit file, managing the service, and the built-in systemd security hardening directives.

Prerequisites​

  • Linux server with systemd (Ubuntu, Debian, CentOS, etc.) and root access
  • Git, curl, and unzip (the Bun installer needs them)
  • Port 7300 free. The server always listens on port 7300.
  • The hardware requirements from the Bun installation

Installation​

1. Install Bun​

Install Bun 1.4.4, the version BugPin 1.3.0 is built and tested with, and copy the binary to /usr/bin/bun, the path the service file starts:

curl -fsSL https://bun.sh/install | bash -s "bun-v1.4.4"
sudo install -m 755 ~/.bun/bin/bun /usr/bin/bun
bun --version
Copy, do not link

The installer places Bun in your home directory. The service runs with ProtectHome=true, which hides /home and /root from it, so a symbolic link from /usr/bin/bun into a home directory does not work. Copy the binary instead.

2. Create BugPin User​

# Create dedicated user for BugPin
sudo useradd -r -s /bin/false bugpin

3. Install BugPin​

Clone the repository first, then create the data directory and hand everything to the bugpin user:

# Clone repository
sudo git clone https://github.com/aranticlabs/bugpin.git /opt/bugpin

# Create the data directory and set ownership
sudo mkdir -p /opt/bugpin/data
sudo chown -R bugpin:bugpin /opt/bugpin

cd /opt/bugpin

# Install dependencies
sudo -u bugpin bun install

# Build assets
sudo -u bugpin bun run build

4. Install systemd Service​

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

# If you installed BugPin in a different location, edit the service file:
sudo nano /etc/systemd/system/bugpin.service
# Update WorkingDirectory and ReadWritePaths

# Reload systemd
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable bugpin

# Start service
sudo systemctl start bugpin

5. Login and Choose a New Password​

Open http://localhost:7300 and log in with the initial credentials. See Login and Choose a New Password.

Usage​

Service Management​

# Start BugPin
sudo systemctl start bugpin

# Stop BugPin
sudo systemctl stop bugpin

# Restart BugPin
sudo systemctl restart bugpin

# Check status
sudo systemctl status bugpin

# Enable auto-start on boot
sudo systemctl enable bugpin

# Disable auto-start
sudo systemctl disable bugpin

View Logs​

# View all logs
sudo journalctl -u bugpin

# Follow logs (live tail)
sudo journalctl -u bugpin -f

# Last 100 lines
sudo journalctl -u bugpin -n 100

# Logs since 1 hour ago
sudo journalctl -u bugpin --since "1 hour ago"

# Logs from today
sudo journalctl -u bugpin --since today

# Logs with timestamps
sudo journalctl -u bugpin -o short-iso

Configuration​

BugPin stores data in ./data relative to the WorkingDirectory in the service file.

To change paths, edit the service file:

sudo nano /etc/systemd/system/bugpin.service

Update WorkingDirectory and ReadWritePaths as needed, then reload:

sudo systemctl daemon-reload
sudo systemctl restart bugpin

Updates​

Stop the service, pull the new code, reinstall dependencies, rebuild, and start the service again. See Upgrading BugPin for the steps, what to back up first, and how to roll back.

Troubleshooting​

Service won't start​

# Check status and logs
sudo systemctl status bugpin
sudo journalctl -u bugpin -n 50

# Common issues:
# 1. Bun not at /usr/bin/bun
ls -l /usr/bin/bun  # Must be a regular file, not a link into /root or /home
# If it is missing or a link, copy the binary:
sudo install -m 755 ~/.bun/bin/bun /usr/bin/bun

# 2. Wrong permissions
sudo chown -R bugpin:bugpin /opt/bugpin

# 3. Port already in use
sudo lsof -i :7300

# 4. Missing dependencies
cd /opt/bugpin
sudo -u bugpin bun install

Check Bun location​

# Find Bun installation
which bun

# Update ExecStart in service file if needed
sudo nano /etc/systemd/system/bugpin.service
ExecStart=/path/to/bun run start

The path must be outside /home and /root, because the service cannot read those directories.

Reset Service​

# Stop and disable
sudo systemctl stop bugpin
sudo systemctl disable bugpin

# Remove service file
sudo rm /etc/systemd/system/bugpin.service

# Reload systemd
sudo systemctl daemon-reload

# Reinstall (follow Installation steps)

Security Hardening​

The systemd service file includes security features:

  • NoNewPrivileges=true - Prevents privilege escalation
  • PrivateTmp=true - Isolated /tmp directory
  • ProtectSystem=strict - Read-only system directories
  • ProtectHome=true - No access to /home directories
  • ReadWritePaths=/opt/bugpin/data - Only write access to data directory

These settings ensure BugPin runs with minimal permissions.

Production Deployment​

Uninstall​

# Stop and disable service
sudo systemctl stop bugpin
sudo systemctl disable bugpin

# Remove service file
sudo rm /etc/systemd/system/bugpin.service

# Reload systemd
sudo systemctl daemon-reload

# Remove BugPin files (optional)
sudo rm -rf /opt/bugpin

# Remove user (optional)
sudo userdel bugpin

Resources​

We use cookies for analytics to improve our website. More information in our Privacy Policy.