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

# 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:

python3 -m venv venv
source venv/bin/activate

On Windows:

python -m venv venv
venv\Scripts\activate

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

Step 3: Install Dependencies

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

# 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:

SECRET_KEY=CHANGE_THIS_TO_A_RANDOM_STRING

Generate a secure secret key:

python3 -c "import secrets; print(secrets.token_hex(32))"

Optional Brickset settings:

BRICKSET_API_KEY=your-api-key-here
BRICKSET_USERNAME=your-username
BRICKSET_PASSWORD=your-password

Step 5: Initialize the Database

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

You should see: "Database initialized successfully!"

Step 6: Create Your Admin User

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

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
2. Click "Register" and create a free account
3. Verify your email address

Step 2: Request API Key

1. Visit API 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:

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:

cp lego_instructions.db lego_instructions.db.backup

Reset database:

rm lego_instructions.db
flask --app run.py init-db
flask --app run.py create-admin

Upgrading to PostgreSQL (Production)

1. Install PostgreSQL

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql

2. Create Database

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

DATABASE_URL=postgresql://lego_user:your-password@localhost/lego_instructions

4. Install PostgreSQL Python driver

pip install psycopg2-binary

5. Initialize database

flask --app run.py init-db

---

🐛 Troubleshooting

Issue: "ModuleNotFoundError"

Solution: Make sure virtual environment is activated and dependencies are installed

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

# Quick fix: restart the application
# Long-term: upgrade to PostgreSQL

Issue: "Permission denied" on uploads

Solution: Check upload directory permissions

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

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:

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! 🧱