getting-started.md

Getting Started

Welcome to The Inventory — an open-source REST API for inventory management built with Django and Wagtail.

This guide will help you install and run the backend API locally in about 10 minutes.

Prerequisites

Before you start, make sure you have:

• Python 3.12 or later — Download Python
• Git — Download Git
• pip — Usually comes with Python
• A terminal/command prompt

Verify Prerequisites

python --version      # Should show Python 3.12+
git --version         # Should show git version
pip --version         # Should show pip version

---

Installation Steps

1. Clone the Repository

git clone https://github.com/Ndevu12/the_inventory.git
cd the_inventory

2. Create a Virtual Environment

A virtual environment isolates project dependencies from your system Python.

On macOS/Linux:

python -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.

3. Install Dependencies

pip install -r requirements.txt

This installs Django, Wagtail, Django REST Framework, and all other required packages.

4. Navigate to Backend Directory

cd src

All Django commands must be run from this directory.

5. Run Database Migrations

python manage.py migrate

This creates the SQLite database and sets up all tables.

6. Create a Superuser (Admin Account)

python manage.py createsuperuser

Follow the prompts to create your admin account:

• Username: (choose a username)
• Email: (your email)
• Password: (choose a strong password)

7. (Optional) Seed Sample Data

To populate the database with sample data for testing:

python manage.py seed_database --clear --create-default

This creates:

• A default tenant organization
• Sample products, categories, and stock locations
• Sample users and test data

8. Start the Development Server

python manage.py runserver

You should see output like:

Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

---

Verify Installation

Access the Admin Interface

Open your browser and visit:

• Wagtail Admin: http://localhost:8000/admin/
• API Root: http://localhost:8000/api/v1/
• API Documentation: http://localhost:8000/api/schema/swagger/

Login to Admin

Use the superuser credentials you created in step 6.

Test the API

Try this in your terminal:

curl http://localhost:8000/api/v1/

You should see a JSON response with available API endpoints.

---

Next Steps

For API Users

• Read the API Documentation for comprehensive endpoint reference
• Check Integration Guide if you're building a frontend

For Deployers

• See Deployment Guide for production setup
• Check Environment Variables for configuration options

For Contributors

• Read Development Guide to set up for contributing
• See Contributing Guide for workflow

For Operators

• See Operations Guide for platform management
• Check Troubleshooting Guide for common issues

---

Troubleshooting

Python Version Error

Error: Python 3.12+ required

Solution: Install Python 3.12 or later from python.org

Port Already in Use

Error: Address already in use

Solution: The default port 8000 is in use. Run on a different port:

python manage.py runserver 8001

Database Migration Error

Error: No such table

Solution: Run migrations again:

python manage.py migrate

Permission Denied (macOS/Linux)

Error: Permission denied

Solution: Make sure your virtual environment is activated:

source venv/bin/activate

More Issues?

See the Troubleshooting Guide for more help.

---

What's Next?

• Explore the API: Visit http://localhost:8000/api/schema/swagger/ to browse all endpoints
• Read the Docs: Check out the API Documentation
• Integrate a Frontend: See Integration Guide
• Deploy to Production: Follow Deployment Guide

---

Need Help?

• 📖 Check the FAQ
• 🐛 See Troubleshooting Guide
• 💬 Open an Issue on GitHub
• 📚 Read the Architecture Guide for technical details

Happy coding! 🚀