From c7bd019f0e1f31b866613dbf39245e814b2ec0a0 Mon Sep 17 00:00:00 2001 From: Xavier Fiechter Date: Tue, 23 Dec 2025 22:44:31 +0100 Subject: [PATCH] . --- BARE_METALL_INSTALL.md | 357 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 BARE_METALL_INSTALL.md diff --git a/BARE_METALL_INSTALL.md b/BARE_METALL_INSTALL.md new file mode 100644 index 0000000..ddc2c0c --- /dev/null +++ b/BARE_METALL_INSTALL.md @@ -0,0 +1,357 @@ +# 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 +```bash +# 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) +```bash +# 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) +```bash +# 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 +```bash +# 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 +```bash +# 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 +```bash +# Start MySQL service +brew services start mysql + +# Secure the installation +mysql_secure_installation +``` + +#### Linux +```bash +# Start MariaDB service +sudo systemctl enable mariadb +sudo systemctl start mariadb + +# Secure the installation +sudo mysql_secure_installation +``` + +### 3. Download and Setup Labelbase + +```bash +# 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 + +```bash +# 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 +```bash +# 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 +```bash +# 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 + +```bash +# 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 +```bash +# 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) +```bash +# 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 + + + + + Label + com.labelbase.app + ProgramArguments + + /bin/bash + -c + 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 + + RunAtLoad + + KeepAlive + + StandardOutPath + /Users/labelbase/labelbase.out + StandardErrorPath + /Users/labelbase/labelbase.err + + +``` + +Load the service: +```bash +launchctl load ~/Library/LaunchAgents/com.labelbase.app.plist +``` + +### Linux (using systemd) + +Create `/etc/systemd/system/labelbase.service`: + +```ini +[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: +```bash +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 + +```bash +# 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.