lego-instructions-manager/SETUP_GUIDE.md

# 🚀 LEGO Instructions Manager - Setup Guide

Complete step-by-step guide to get your LEGO Instructions Manager up and running.

## 📋 Prerequisites Checklist

Before you begin, ensure you have:
- [ ] Python 3.8 or higher installed
- [ ] Git installed
- [ ] Terminal/Command Prompt access
- [ ] Gitea repository access (https://gitea.hideawaygaming.com.au)
- [ ] (Optional) Brickset account for API access

---

## 🔧 Step-by-Step Installation

### Step 1: Clone the Repository

```bash
# Clone from your Gitea instance
git clone https://gitea.hideawaygaming.com.au/jessikitty/lego-instructions-manager.git

# Navigate into the project
cd lego-instructions-manager
```

### Step 2: Set Up Python Virtual Environment

**On Linux/Mac:**
```bash
python3 -m venv venv
source venv/bin/activate
```

**On Windows:**
```bash
python -m venv venv
venv\Scripts\activate
```

You should see `(venv)` in your terminal prompt when activated.

### Step 3: Install Dependencies

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

This will install all required packages including Flask, SQLAlchemy, and more.

### Step 4: Configure Environment Variables

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env with your preferred text editor
nano .env  # or vim, code, etc.
```

**Required settings to change:**
```env
SECRET_KEY=CHANGE_THIS_TO_A_RANDOM_STRING
```

Generate a secure secret key:
```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

**Optional Brickset settings:**
```env
BRICKSET_API_KEY=your-api-key-here
BRICKSET_USERNAME=your-username
BRICKSET_PASSWORD=your-password
```

### Step 5: Initialize the Database

```bash
# Create the database and tables
flask --app run.py init-db
```

You should see: "Database initialized successfully!"

### Step 6: Create Your Admin User

```bash
flask --app run.py create-admin
```

Follow the prompts to create your admin account:
- Username: Choose your username
- Email: Your email address
- Password: Choose a secure password (min 6 characters)

### Step 7: Run the Application

```bash
python run.py
```

You should see output like:
```
 * Running on http://0.0.0.0:5000
 * Debug mode: on
```

### Step 8: Access the Application

Open your web browser and navigate to:
```
http://localhost:5000
```

You should see the LEGO Instructions Manager homepage!

---

## 🎯 First Time Setup Tasks

### 1. Login
- Click "Login" in the navigation
- Enter the admin credentials you created
- You'll be redirected to the dashboard

### 2. Add Your First Set
- Click "Add Set" in the navigation
- If Brickset is configured, try searching for a set
- Otherwise, manually enter set details
- Click "Add Set" to save

### 3. Upload Instructions
- From the set detail page, click "Upload Instructions"
- Select PDF or image files
- Click "Upload" to save

---

## 🔑 Getting Brickset API Access

### Step 1: Create Brickset Account
1. Go to [https://brickset.com](https://brickset.com)
2. Click "Register" and create a free account
3. Verify your email address

### Step 2: Request API Key
1. Visit [API Documentation](https://brickset.com/article/52664/api-version-3-documentation)
2. Fill out the API key request form
3. Wait for approval (usually within 24 hours)
4. You'll receive your API key via email

### Step 3: Configure API Credentials
1. Open your `.env` file
2. Add your credentials:
```env
BRICKSET_API_KEY=your-api-key-from-email
BRICKSET_USERNAME=your-brickset-username
BRICKSET_PASSWORD=your-brickset-password
```
3. Save the file and restart the application

---

## 🗄️ Database Management

### Using SQLite (Default)
The default database is SQLite, stored in `lego_instructions.db`.

**Backup your database:**
```bash
cp lego_instructions.db lego_instructions.db.backup
```

**Reset database:**
```bash
rm lego_instructions.db
flask --app run.py init-db
flask --app run.py create-admin
```

### Upgrading to PostgreSQL (Production)

1. **Install PostgreSQL**
```bash
# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql
```

2. **Create Database**
```bash
sudo -u postgres psql
CREATE DATABASE lego_instructions;
CREATE USER lego_user WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE lego_instructions TO lego_user;
\q
```

3. **Update .env**
```env
DATABASE_URL=postgresql://lego_user:your-password@localhost/lego_instructions
```

4. **Install PostgreSQL Python driver**
```bash
pip install psycopg2-binary
```

5. **Initialize database**
```bash
flask --app run.py init-db
```

---

## 🐛 Troubleshooting

### Issue: "ModuleNotFoundError"
**Solution:** Make sure virtual environment is activated and dependencies are installed
```bash
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
```

### Issue: "Database is locked"
**Solution:** SQLite can only handle one write at a time. For production, use PostgreSQL
```bash
# Quick fix: restart the application
# Long-term: upgrade to PostgreSQL
```

### Issue: "Permission denied" on uploads
**Solution:** Check upload directory permissions
```bash
chmod -R 755 app/static/uploads
```

### Issue: "Brickset API not responding"
**Solution:** Verify your credentials and check Brickset status
- Check your API key, username, and password in `.env`
- Verify your Brickset account is active
- Check if Brickset is having issues: https://brickset.com

### Issue: "Port 5000 already in use"
**Solution:** Change the port in `run.py`
```python
app.run(host='0.0.0.0', port=5001, debug=True)
```

---

## 📱 Development vs Production

### Development Mode (Current Setup)
- Debug mode enabled
- SQLite database
- Runs on localhost:5000
- Auto-reloads on code changes

### Production Deployment
For production, you'll need:
1. PostgreSQL database
2. Gunicorn WSGI server
3. Nginx reverse proxy
4. SSL/TLS certificates
5. Proper SECRET_KEY
6. Regular backups

**Quick production start:**
```bash
export FLASK_ENV=production
gunicorn -w 4 -b 0.0.0.0:8000 "run:app"
```

---

## 🎓 Next Steps

1. ✅ Explore the dashboard and statistics
2. ✅ Add multiple sets to your collection
3. ✅ Upload various instruction formats (PDF, images)
4. ✅ Try searching and filtering
5. ✅ Test Brickset integration
6. ✅ Customize themes and categories
7. ✅ Regular backups of your database

---

## 📚 Additional Resources

- **Flask Documentation**: https://flask.palletsprojects.com
- **Brickset API Docs**: https://brickset.com/article/52664
- **SQLAlchemy Docs**: https://docs.sqlalchemy.org
- **Bootstrap 5 Docs**: https://getbootstrap.com

---

## 💡 Pro Tips

1. **Regular Backups**: Set up automated database backups
2. **Organize Early**: Establish naming conventions for sets
3. **Use Brickset**: It saves time on data entry
4. **Image Quality**: Higher resolution images work better
5. **PDF Organization**: Name PDFs clearly before upload

---

## 🤝 Getting Help

If you encounter issues:
1. Check this guide's troubleshooting section
2. Review application logs
3. Check the main README.md
4. Create an issue on Gitea

---

**Happy Building! 🧱**