labelbase/BARE_METALL_INSTALL.md

Labelbase Bare Metal Installation Guide

This guide will help you install and run Labelbase directly on macOS and Linux systems, based on the RaspiBlitz installation script.

Prerequisites

Common Requirements

• Git
• Python 3.8 or higher
• pip (Python package manager)
• virtualenv
• MySQL/MariaDB server

System-Specific Requirements

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required packages
brew install python3 mysql git
brew install pkg-config mysql-client

Linux (Ubuntu/Debian)

# Update package list
sudo apt update

# Install required packages
sudo apt install -y \
    mariadb-server \
    mariadb-client \
    default-libmysqlclient-dev \
    build-essential \
    python3 \
    python3-pip \
    python3-venv \
    git \
    libpcre3-dev

Linux (CentOS/RHEL/Fedora)

# For CentOS/RHEL 8+
sudo dnf install -y \
    mariadb-server \
    mariadb-devel \
    python3 \
    python3-pip \
    python3-virtualenv \
    git \
    gcc \
    gcc-c++ \
    make

# For older versions, use yum instead of dnf

Installation Steps

1. Create Application User (Optional but Recommended)

macOS

# Create a new user (optional on macOS for development)
sudo dscl . -create /Users/labelbase
sudo dscl . -create /Users/labelbase UserShell /bin/bash
sudo dscl . -create /Users/labelbase RealName "Labelbase User"
sudo dscl . -create /Users/labelbase UniqueID 1001
sudo dscl . -create /Users/labelbase PrimaryGroupID 20
sudo dscl . -create /Users/labelbase NFSHomeDirectory /Users/labelbase
sudo createhomedir -c -u labelbase

Linux

# Create system user
sudo adduser --system --group --shell /bin/bash --home /home/labelbase labelbase
sudo -u labelbase cp -r /etc/skel/. /home/labelbase/

2. Start Database Service

macOS

# Start MySQL service
brew services start mysql

# Secure the installation
mysql_secure_installation

Linux

# Start MariaDB service
sudo systemctl enable mariadb
sudo systemctl start mariadb

# Secure the installation
sudo mysql_secure_installation

3. Download and Setup Labelbase

# Switch to labelbase user (if created) or use your regular user
# sudo su - labelbase  # (if using dedicated user)

# Set variables
LABELBASE_HOME="$HOME"  # or /home/labelbase if using dedicated user
LABELBASE_REPO="https://github.com/Labelbase/Labelbase/"
LABELBASE_VERSION="2.2.1"

# Clone the repository
git clone $LABELBASE_REPO $LABELBASE_HOME/labelbase
cd $LABELBASE_HOME/labelbase

# Checkout specific version
git checkout $LABELBASE_VERSION

# Create virtual environment
python3 -m venv $LABELBASE_HOME/ENV

# Activate virtual environment
source $LABELBASE_HOME/ENV/bin/activate

# Install Python dependencies
pip install --upgrade pip
pip install --no-cache-dir -r $LABELBASE_HOME/labelbase/django/requirements.txt

4. Database Configuration

# Generate a secure password
MYSQL_PASSWORD=$(openssl rand -base64 32 | tr -d '+/' | fold -w 32 | head -n 1)

# Create exports file
cat > $LABELBASE_HOME/exports.sh << EOF
export MYSQL_PASSWORD=$MYSQL_PASSWORD
export DATABASE_URL=mysql://ulabelbase:$MYSQL_PASSWORD@localhost:3306/labelbase
EOF

chmod 755 $LABELBASE_HOME/exports.sh

Create Database and User

macOS

# Connect to MySQL
mysql -u root -p

# In MySQL prompt:
CREATE DATABASE labelbase;
CREATE USER 'ulabelbase'@'localhost' IDENTIFIED BY 'YOUR_GENERATED_PASSWORD';
GRANT ALL PRIVILEGES ON labelbase.* TO 'ulabelbase'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Linux

# Connect to MariaDB
sudo mysql

# In MariaDB prompt:
CREATE DATABASE labelbase;
CREATE USER 'ulabelbase'@'localhost' IDENTIFIED BY 'YOUR_GENERATED_PASSWORD';
GRANT ALL PRIVILEGES ON labelbase.* TO 'ulabelbase'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Note: Replace YOUR_GENERATED_PASSWORD with the password generated in the previous step.

5. Django Setup

# Navigate to Django directory
cd $LABELBASE_HOME/labelbase/django

# Activate virtual environment and load environment variables
source $LABELBASE_HOME/ENV/bin/activate
source $LABELBASE_HOME/exports.sh

# Run Django migrations
python manage.py makemigrations --noinput
python manage.py migrate --noinput
python manage.py collectstatic --noinput

# Create a superuser (optional)
python manage.py createsuperuser

6. Running Labelbase

Development Mode

# Activate environment
source $LABELBASE_HOME/ENV/bin/activate
source $LABELBASE_HOME/exports.sh

# Navigate to Django directory
cd $LABELBASE_HOME/labelbase/django

# Run development server
python manage.py runserver 0.0.0.0:8089

# Access at: http://localhost:8089

Production Mode (using Gunicorn)

# Install Gunicorn if not already installed
pip install gunicorn

# Run with Gunicorn
source $LABELBASE_HOME/ENV/bin/activate
source $LABELBASE_HOME/exports.sh
cd $LABELBASE_HOME/labelbase/django

gunicorn labellabor.wsgi:application -b 0.0.0.0:8089 --reload

Creating System Services (Optional)

macOS (using LaunchAgent)

Create a plist file at ~/Library/LaunchAgents/com.labelbase.app.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.labelbase.app</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd /Users/labelbase/labelbase/django && source /Users/labelbase/ENV/bin/activate && source /Users/labelbase/exports.sh && gunicorn labellabor.wsgi:application -b 0.0.0.0:8089</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/labelbase/labelbase.out</string>
    <key>StandardErrorPath</key>
    <string>/Users/labelbase/labelbase.err</string>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/com.labelbase.app.plist

Linux (using systemd)

Create /etc/systemd/system/labelbase.service:

[Unit]
Description=Labelbase Application
After=mariadb.service

[Service]
Type=simple
User=labelbase
WorkingDirectory=/home/labelbase/labelbase/django
Environment="HOME_PATH=/home/labelbase"
ExecStart=/bin/bash -c 'source /home/labelbase/ENV/bin/activate && source /home/labelbase/exports.sh && gunicorn labellabor.wsgi:application -b 0.0.0.0:8089'
Restart=always
TimeoutSec=120
RestartSec=30

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable labelbase
sudo systemctl start labelbase
sudo systemctl status labelbase

Troubleshooting

Common Issues

1. Database Connection Errors

   • Ensure MySQL/MariaDB is running
   • Verify database credentials in exports.sh
   • Check if the database user has proper permissions

2. Python Package Issues

   • Make sure virtual environment is activated
   • Try upgrading pip: pip install --upgrade pip
   • Install packages one by one if requirements.txt fails

3. Port Already in Use

   • Change the port in the run command: gunicorn ... -b 0.0.0.0:8090
   • Find and kill processes using the port: lsof -ti:8089 | xargs kill -9

4. Permission Errors

   • Ensure proper ownership of files: sudo chown -R labelbase:labelbase /home/labelbase
   • Check file permissions: chmod 755 /home/labelbase/exports.sh

Logs and Debugging

• Development server logs: Displayed in terminal
• Gunicorn logs: Use --log-file flag for logging
• System service logs (Linux): sudo journalctl -u labelbase -f
• Database logs: Check MySQL/MariaDB error logs

Stopping the Application

# If running in development mode
Ctrl+C

# If running as system service
# macOS:
launchctl unload ~/Library/LaunchAgents/com.labelbase.app.plist

# Linux:
sudo systemctl stop labelbase

Security Considerations

1. Firewall Configuration

   • Only expose necessary ports
   • Consider using a reverse proxy (nginx/apache) for production

2. Database Security

   • Use strong passwords
   • Limit database user permissions
   • Consider encrypting database connections

3. Application Security

   • Keep dependencies updated
   • Use HTTPS in production
   • Regular security updates

4. File Permissions

   • Ensure proper file ownership and permissions
   • Limit access to configuration files

This guide provides a foundation for running Labelbase on bare metal systems. Adjust paths, ports, and configurations according to your specific needs and security requirements.