Initial commit - LEGO Instructions Manager v1.5.0
This commit is contained in:
324
SETUP_GUIDE.md
Normal file
324
SETUP_GUIDE.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# 🚀 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! 🧱**
|
||||
Reference in New Issue
Block a user