labelbase/DEVELOPMENT_GUIDE.md

# Labelbase Development Guide

Quick reference for working with and developing Labelbase in Docker.

## Initial Setup

### 1. Clone and Setup
```bash
git clone https://github.com/Labelbase/Labelbase/
cd Labelbase
```

### 2. Generate MySQL Passwords
```bash
./make-exports.sh
```

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

### 3. Build and Run
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
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

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

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

### Check What Django Sees
```bash
# 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
```bash
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!)
```bash
#!/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**:
```bash
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:
```bash
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
```bash
# 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:
```bash
docker-compose exec labelbase_django python manage.py collectstatic --noinput
```

### Running Tests
```bash
docker-compose exec labelbase_django python manage.py test
```

### Python Dependencies
Add to `requirements.txt`, then:
```bash
docker-compose up --build -d
```

### Database Migrations
```bash
# 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

```bash
# 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`