Miare Shop Project

This project is a simple e-commerce backend built with Django, Django REST Framework, DRF SimpleJWT for authentication, and Redis (optionally) for caching. It also uses drf-yasg for Swagger/OpenAPI documentation and a per-app logging configuration.

---

1. Project Setup

1.1 Clone and Enter the Project Directory

git clone git@github.com:qzzzle/miareshop.git
cd miare_shop

(If the repository is private, ensure your SSH keys or GitHub credentials have access.)

1.2 Create and Activate a Virtual Environment

python -m venv venv
source venv/bin/activate

(For Windows:

.\venv\Scripts\activate

*)

1.3 Install Dependencies

pip install -r requirements.txt

This includes packages like:

• Django
• djangorestframework
• djangorestframework-simplejwt
• django-redis
• drf-yasg
• python-decouple
• And more…

---

2. Environment Variables

2.1 Copy the Example Env File

We provide an example environment file called env_example (or .env.example). Copy or rename it to .env:

cp env_example .env

Open .env in a text editor to fill or adjust the values:

SECRET_KEY=your-secret-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
JWT_ACCESS_TOKEN_LIFETIME=5
JWT_REFRESH_TOKEN_LIFETIME=1440
REST_FRAMEWORK_PAGE_SIZE=10
CACHE_BACKEND=redis
REDIS_LOCATION=redis://127.0.0.1:6379/1
# or memcache
# MEMCACHE_LOCATION=127.0.0.1:11211

Important:

• SECRET_KEY should be changed to a more secure value in production.
• If Redis is installed locally, you can leave REDIS_LOCATION as is. Otherwise, if you prefer memcache, set CACHE_BACKEND=memcache and update MEMCACHE_LOCATION.

---

3. Logs Directory

Create a folder named logs at the project root (the same level as manage.py). The Django logging configuration in core/settings.py writes logs for each app (e.g., accounts.log, products.log, purchases.log) to that directory:

mkdir logs

Django will create the actual log files the first time the app writes a log.

---

4. Database Migrations

Run the usual Django migration commands:

python manage.py makemigrations
python manage.py migrate

This sets up your database schema (default: SQLite) as configured in core/settings.py.

---

5. Create a Superuser

You can create an admin account for the Django Admin:

python manage.py createsuperuser

Enter username, email, and password when prompted.

---

6. Running the Application

Launch the development server:

python manage.py runserver

By default, this starts at http://127.0.0.1:8000/. Check /admin/ to log into Django’s admin panel, or /swagger/ for your auto-generated API documentation.

---

7. Testing

7.1 Run Test Suite

python manage.py test

This will run all unit tests.

7.2 Optional: Coverage

pip install coverage
coverage run --source='.' manage.py test
coverage report -m

You should see a coverage report for each file, hopefully at or near 100%.

---

8. Redis Setup (Optional)

If you chose CACHE_BACKEND=redis in your .env, make sure you have a local Redis instance running on the port you specified (usually 6379). For example, on Ubuntu:

sudo apt-get update
sudo apt-get install redis-server
sudo service redis-server start

Or use Docker:

docker run -p 6379:6379 redis:latest

Confirm Redis is running:

redis-cli ping

Should return PONG if successful.

---

9. Swagger API Documentation

1. Make sure drf_yasg is in your INSTALLED_APPS.
2. Visit http://127.0.0.1:8000/swagger/ (or your domain) to view interactive Swagger UI.
3. You can also access http://127.0.0.1:8000/redoc/ for Redoc documentation if desired.

---

10. Postman Collection

We have a Postman collection located at docs/postman.json. You can import this file into Postman to quickly test the following endpoints:

• JWT token acquisition
• User profile retrieval
• Products listing
• Shopping cart endpoints

In Postman:

1. Click Import in the upper-left corner.
2. Select the docs/postman.json file from the project.
3. Explore the imported collection (named “Miare Shop API” or similar) and run requests as needed.

---

11. Project Structure Overview

miare_shop/
 ├─ logs/                 # Logging output files for each app
 │   ├─ accounts.log
 │   ├─ products.log
 │   └─ purchases.log
 ├─ accounts/
 │   ├─ models.py         # Custom User model
 │   ├─ admin.py
 │   ├─ serializers.py
 │   ├─ views.py
 │   ├─ urls.py
 │   ├─ tests.py
 ├─ products/
 │   ├─ models.py         # Product model
 │   ├─ admin.py
 │   ├─ serializers.py
 │   ├─ views.py
 │   ├─ urls.py
 │   ├─ tests.py
 ├─ purchases/
 │   ├─ models.py         # Cart, CartItem
 │   ├─ admin.py
 │   ├─ serializers.py
 │   ├─ views.py
 │   ├─ urls.py
 │   ├─ tests.py
 ├─ utils/
 │   ├─ managers.py       # ActiveManager
 │   ├─ models.py         # BaseModel
 │   ├─ paginations.py
 │   ├─ messages.py
 ├─ core/
 │   ├─ settings.py       # Main Django settings
 │   ├─ urls.py           # URL routing + Swagger setup
 │   ├─ wsgi.py
 │   ├─ asgi.py
 ├─ docs/
 │   ├─ postman.json      # Postman collection for testing
 ├─ env_example           # Template environment file
 ├─ manage.py
 └─ README.md             # This readme

---

12. Common Troubleshooting

1. Django can’t find swagger-ui.html
   • Make sure drf_yasg is in INSTALLED_APPS and APP_DIRS=True in TEMPLATES.
2. Logs don’t appear
   • Ensure you created the logs directory and that the logger in core/settings.py references logs/*.log properly.
3. No module named redis
   • Make sure CACHE_BACKEND=redis in .env matches your installed dependencies. If you’re not using Redis, switch to memcache or local memory.

---

13. Next Steps

• Adjust settings or environment variables for production (e.g., set DEBUG=False, secure your SECRET_KEY).
• Integrate your own CI/CD pipeline to run tests and coverage.
• Extend or refine the logging config for more granular logs, or use log rotation.

Enjoy your Miare Shop project!