Django REST API Boilerplate

This is a robust and scalable boilerplate for building a modern REST API using Python and the Django framework. It is designed to be a secure, performant, and maintainable foundation for a variety of web applications.

This backend is completely decoupled from the frontend, allowing you to choose any frontend framework (like React, Vue, Angular, or a mobile app) to consume its API.

Why This Boilerplate?

Setting up a secure, scalable Django backend with modern tooling like split settings, JWT authentication, and API documentation can take hours. This boilerplate gives you a production-ready foundation for building SaaS applications and APIs, letting you focus on writing business logic instead of boilerplate.

Key Features & Technologies

• Python 3 & Django 5: The core web framework.
• Docker & Docker Compose: For a consistent, containerized development and production environment with PostgreSQL.
• Django REST Framework (DRF): For building the REST API.
• PostgreSQL: The recommended database for production (and for Docker development).
• django-allauth & dj-rest-auth: For robust and secure email-based authentication.
• drf-yasg: For generating Swagger and ReDoc API documentation.
• Split Settings: Configuration is split for dev and prod environments.
• Gunicorn: A production-ready WSGI server is included in the Docker setup.

Getting Started

You have two primary options for setting up the project. Docker is the recommended approach as it provides a more consistent environment.

Environment Setup (Do This First!)

This project uses environment variables for configuration. Create a .env file in the root directory by copying the example:

cp .env.example .env

Now, open .env and fill in any necessary secrets (like your SECRET_KEY and STRIPE_KEY). The default settings are configured to work with both Docker and non-Docker setups out of the box.

Option 1: Running with Docker (Recommended)

This is the easiest and most reliable way to get started. It automatically sets up a PostgreSQL database and runs the Django application in isolated containers.

Prerequisites: Docker and Docker Compose must be installed.

1. Build and Run the Containers:

   docker-compose up --build

2. Create a Superuser (in a separate terminal):

   Once the containers are running, you can execute commands inside the backend container.

   docker-compose exec backend python manage.py createsuperuser

That's it! The API will be running and available at http://localhost:8000.

Option 2: Running Locally with a Virtual Environment

Choose this option if you prefer to manage the Python environment and database on your host machine directly.

1. Activate the Virtual Environment:

   The project is configured to use a virtual environment at .venv/.

   source .venv/bin/activate

2. Install Dependencies:

   pip install -r backend/requirements.txt

3. Run Database Migrations:

   The default local setup uses SQLite. The manage.py script is inside the backend/ directory.

   cd backend
   python manage.py migrate

4. Create a Superuser:

   # Make sure you are still in the 'backend' directory
   python manage.py createsuperuser

5. Run the Development Server:

   Go back to the root directory and use the provided script:

   cd ..
   ./devserver.sh

The API will now be running.

API Endpoints & Documentation

Once the server is running (via Docker or locally), you can explore the API:

• Swagger UI: http://localhost:8000/swagger/
• ReDoc: http://localhost:8000/redoc/
• Admin Panel: http://localhost:8000/admin/

Here are some of the primary endpoints available:

Endpoint	Method	Description
/api/auth/register/	POST	Register a new user.
/api/auth/login/	POST	Login using email and password.
/api/auth/logout/	POST	Invalidate the user's session/token.
/api/auth/user/	GET	Fetch current authenticated user data.
/api/billing/subscribe/	POST	Create a new Stripe subscription.

Deployment

For production, use the core/settings/prod.py configuration. You can deploy this project to services like Railway, Render, or AWS Elastic Beanstalk using either a Docker-based deployment or a traditional buildpack.

Static Files (Production)

Before deploying, you must collect all of Django's static files (for the admin panel, etc.) into a single directory. Run this command from the backend/ directory:

# From inside the 'backend' directory:
python manage.py collectstatic --noinput

Production Server Command (Non-Docker)

If deploying without Docker, use a production-grade WSGI server like Gunicorn. The command should specify the production settings file:

gunicorn core.wsgi:application --env DJANGO_SETTINGS_MODULE=core.settings.prod

Make sure to set all your environment variables (from the .env file) on your hosting platform.