labelbase/DEVELOPMENT_GUIDE.md

Labelbase Development Guide

Quick reference for working with and developing Labelbase in Docker.

Initial Setup

1. Clone and Setup

git clone https://github.com/Labelbase/Labelbase/
cd Labelbase

2. Generate MySQL Passwords

./make-exports.sh

This creates exports.sh with random passwords. Backup this file!

3. Build and Run

source exports.sh && ./build-and-run-labelbase.sh

The source exports.sh loads the passwords into your shell, then the script uses them.

Access at: http://127.0.0.1:8080

---

Daily Development Workflow

Start/Stop Services

# Start (always source exports.sh first!)
source exports.sh && docker-compose up -d

# Stop
docker-compose down

# Rebuild and restart (after code changes)
source exports.sh && docker-compose up --build -d

# Or use the main script
source exports.sh && ./build-and-run-labelbase.sh

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f labelbase_django
docker-compose logs -f labelbase_mysql
docker-compose logs -f labelbase_nginx

# Search logs
docker-compose logs labelbase_django | grep -i error

Access Container Shell

# Django container (most common)
docker-compose exec labelbase_django bash

# MySQL container
docker-compose exec labelbase_mysql bash

# Nginx container
docker-compose exec labelbase_nginx sh

Django Management Commands

# From host
docker-compose exec labelbase_django python manage.py <command>

# Or from inside container
docker-compose exec labelbase_django bash
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
python manage.py shell

Database Operations

# Access MySQL CLI
docker-compose exec labelbase_mysql mysql -u ulabelbase -p labelbase

# Backup database
docker-compose exec labelbase_mysql mysqldump -u root -p labelbase > backup.sql

# Restore database
docker-compose exec -T labelbase_mysql mysql -u root -p labelbase < backup.sql

---

Common Tasks

Reset config.ini (if passwords change)

docker-compose exec labelbase_django bash
rm /app/config.ini
python manage.py make_config
exit
docker-compose restart labelbase_django

Clean Rebuild (fresh start, deletes volumes!!)

❌ DANGER ZONE

docker-compose down -v
source exports.sh && docker-compose up --build -d

⚠️ Warning: -v deletes volumes including database data!

Check What Django Sees

# Check environment variables
docker-compose exec labelbase_django env | grep MYSQL

# Check config.ini
docker-compose exec labelbase_django cat /app/config.ini

# Check database connection
docker-compose exec labelbase_django python manage.py dbshell

Update from Git

git pull origin master
source exports.sh && ./build-and-run-labelbase.sh

The script automatically detects updates and rebuilds if needed.

---

Configuration Files

exports.sh (IMPORTANT - backup this!)

#!/bin/bash
export MYSQL_ROOT_PASSWORD="your_password_here"
export MYSQL_PASSWORD="your_password_here"

• Generated by ./make-exports.sh
• Contains MySQL passwords
• Source before running docker-compose: source exports.sh
• Add to .gitignore - contains secrets!

config.ini (auto-generated, persisted)

• Located at /app/config.ini inside Django container
• Generated from environment variables on first run by python manage.py make_config
• Not overwritten on subsequent runs (preserves user settings)
• Force regenerate: rm /app/config.ini then restart

docker-compose.yml

Uses environment variables like ${MYSQL_PASSWORD} from your shell (after sourcing exports.sh).

---

Troubleshooting

"Access denied for user 'ulabelbase'@'localhost'"

Cause: Old config.ini with wrong password from previous build

Solution:

docker-compose exec labelbase_django bash
rm /app/config.ini
python manage.py make_config
exit
docker-compose restart labelbase_django

"MYSQL_PASSWORD variable is not set" warnings

Cause: Forgot to source exports.sh

Solution: Always use source exports.sh && docker-compose up

These warnings appear at parse time but are harmless if you source exports.sh before running the command.

"Can't connect to MySQL server"

Cause: Database not ready yet

Solution: Wait 15 seconds (run.sh has a built-in delay) or check logs:

docker-compose logs labelbase_mysql

Django can't see code changes

• Volume mounting issue
• Solution: docker-compose restart labelbase_django
• Or use --reload in gunicorn (already enabled)

Port 8080 already in use

# Find what's using it
lsof -i :8080

# Change port in docker-compose.yml
ports:
  - "127.0.0.1:8081:8080"  # Use 8081 instead

---

Development Tips

Live Code Reloading

Django container mounts ./django:/app, so changes are live. Gunicorn runs with --reload flag.

Static Files

After changing CSS/JS:

docker-compose exec labelbase_django python manage.py collectstatic --noinput

Running Tests

docker-compose exec labelbase_django python manage.py test

Python Dependencies

Add to requirements.txt, then:

docker-compose up --build -d

Database Migrations

# Create migrations
docker-compose exec labelbase_django python manage.py makemigrations

# Apply migrations
docker-compose exec labelbase_django python manage.py migrate

# Show migration status
docker-compose exec labelbase_django python manage.py showmigrations

---

Production Deployment

See main README for:

• Setting up nginx reverse proxy
• SSL certificates with certbot
• Domain configuration
• Firewall rules

---

Quick Command Reference

# Build and run
source exports.sh && ./build-and-run-labelbase.sh

# Stop
docker-compose down

# Logs
docker-compose logs -f

# Shell
docker-compose exec labelbase_django bash
or
source exports.sh && docker-compose exec labelbase_django bash

# Reset everything (DANGER: deletes data!)
docker-compose down -v && source exports.sh && docker-compose up --build -d

# Reset config.ini (if passwords changed)
docker-compose exec labelbase_django rm /app/config.ini
docker-compose restart labelbase_django

---

Environment Variables Reference

Variable	Purpose	Default
MYSQL_ROOT_PASSWORD	MySQL root password	(required)
MYSQL_PASSWORD	MySQL user password	(required)
MYSQL_DATABASE	Database name	labelbase
MYSQL_USER	Database user	ulabelbase
MYSQL_HOST	Database hostname	labelbase_mysql
MYSQL_PORT	Database port	3306

Set in exports.sh file and load with source exports.sh before running docker-compose.

Note I: You may see warnings like "variable is not set" when running docker-compose commands. These appear at parse time but are harmless - the variables are properly set when you source exports.sh before the command.

NOTE II: Some of the variables are hard coded or may need to be changed in the docker-compose.yml file manually.

---

Need Help?

• Check logs: docker-compose logs -f
• View settings: docker-compose exec labelbase_django cat /app/config.ini
• Check environment: docker-compose exec labelbase_django env | grep MYSQL
• Access Django shell: docker-compose exec labelbase_django python manage.py shell