• Stars
    star
    1,918
  • Rank 24,174 (Top 0.5 %)
  • Language
    Python
  • License
    MIT License
  • Created over 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Django 5, React, Bootstrap 5 with Python 3 and webpack project boilerplate

Django React Boilerplate

Contributor Covenant License: MIT

About

A Django project boilerplate/template with lots of state of the art libraries and tools like:

For continuous integration, a Github Action configuration .github/workflows/main.yml is included.

Also, includes a Render.com render.yaml and a working Django production.py settings, enabling easy deployments with 'Deploy to Render' button. The render.yaml includes the following:

  • PostgreSQL, for DB
  • Redis, for Celery

This is a good starting point for modern Python/JavaScript web projects.

Project bootstrap main Known Vulnerabilities

  • Make sure you have Python 3.11 installed
  • Install Django with pip install django, to have the django-admin command available.
  • Open the command line and go to the directory you want to start your project in.
  • Start your project using:
    django-admin startproject theprojectname --extension py,yml,json --name Procfile,Dockerfile,docker-compose.yml,README.md,.env.example,.gitignore,Makefile,render.yaml --template=https://github.com/vintasoftware/django-react-boilerplate/archive/boilerplate-release.zip
    
    Alternatively, you may start the project in the current directory by placing a . right after the project name, using the following command:
    django-admin startproject theprojectname . --extension py,yml,json --name Procfile,Dockerfile,docker-compose.yml,README.md,.env.example,.gitignore,Makefile,render.yaml --template=https://github.com/vintasoftware/django-react-boilerplate/archive/boilerplate-release.zip
    

In the next steps, always remember to replace theprojectname with your project's name

  • Above: don't forget the --extension and --name params!
  • Change the first line of README to the name of the project
  • Add an email address to the ADMINS settings variable in {{project_name}}/backend/{{project_name}}/settings/base.py
  • Change the SERVER_EMAIL to the email address used to send e-mails in {{project_name}}/backend/{{project_name}}/settings/production.py

After completing ALL of the above, remove this Project bootstrap section from the project README. Then follow Running below.

Running

Tools

Setup

  • Inside the backend folder, do the following:
    • Create a copy of {{project_name}}/settings/local.py.example:
      cp {{project_name}}/settings/local.py.example {{project_name}}/settings/local.py
    • Create a copy of .env.example: cp .env.example .env

If you are using Docker:

  • Open the /backend/.env file on a text editor and uncomment the line DATABASE_URL=postgres://{{project_name}}:password@db:5432/{{project_name}}
  • Open a new command line window and go to the project's directory
  • Run the initial setup: make docker_setup
  • Create the migrations for users app:
    make docker_makemigrations
  • Run the migrations: make docker_migrate
  • Run the project: make docker_up
  • Access http://localhost:8000 on your browser and the project should be running there
    • When you run make docker_up, some containers are spinned up (frontend, backend, database, etc) and each one will be running on a different port
    • The container with the React app uses port 3000. However, if you try accessing it on your browser, the app won't appear there and you'll probably see a blank page with the "Cannot GET /" error
    • This happens because the container responsible for displaying the whole application is the Django app one (running on port 8000). The frontend container is responsible for providing a bundle with its assets for django-webpack-loader to consume and render them on a Django template
  • To access the logs for each service, run: make docker_logs <service name> (either backend, frontend, etc)
  • To stop the project, run: make docker_down

Adding new dependencies

  • Open a new command line window and go to the project's directory
  • Update the dependencies management files by performing any number of the following steps:
    • To add a new frontend dependency, run npm install <package name> --save

      The above command will update your package.json, but won't make the change effective inside the container yet

    • To add a new backend dependency, run docker compose run backend --rm bash to open an interactive shell and then run poetry add {dependency} to add the dependency. If the dependency should be only available for development user append -G dev to the command.
    • After updating the desired file(s), run make docker_update_dependencies to update the containers with the new dependencies

    The above command will stop and re-build the containers in order to make the new dependencies effective

If you are not using Docker:

Setup and run the frontend app

  • Open a new command line window and go to the project's directory
  • npm install
  • npm run start
    • This is used to serve the frontend assets to be consumed by django-webpack-loader and not to run the React application as usual, so don't worry if you try to check what's running on port 3000 and see an error on your browser

Setup the backend app

  • Open the /backend/.env file on a text editor and do one of the following:
    • If you wish to use SQLite locally, uncomment the line DATABASE_URL=sqlite:///backend/db.sqlite3
    • If you wish to use PostgreSQL locally, uncomment and edit the line DATABASE_URL=postgres://{{project_name}}:password@db:5432/{{project_name}} in order to make it correctly point to your database URL
      • The url format is the following: postgres://USER:PASSWORD@HOST:PORT/NAME
    • If you wish to use another database engine locally, add a new DATABASE_URL setting for the database you wish to use
      • Please refer to dj-database-url on how to configure DATABASE_URL for commonly used engines
  • Open a new command line window and go to the project's directory
  • run poetry install

Run the backend app

  • With the virtualenv enabled, go to the backend directory
  • Create the migrations for users app: poetry run python manage.py makemigrations
  • Run the migrations: poetry run python manage.py migrate
  • Run the project: poetry run python manage.py runserver
  • Open a browser and go to http://localhost:8000 to see the project running

Setup Celery

  • poetry run python manage.py celery

Mailhog

  • For development, we use Mailhog to test our e-mail workflows, since it allows us to inspect the messages to validate they're correctly built
    • Docker users already have it setup and running once they start the project
    • For non-Docker users, please have a look here for instructions on how to setup Mailhog on specific environments

The project expects Mailhog SMTP server to be running on port 1025, you may alter that by changing EMAIL_PORT on settings

Testing

make test

Will run django tests using --keepdb and --parallel. You may pass a path to the desired test module in the make command. E.g.:

make test someapp.tests.test_views

Adding new pypi libs

To add a new backend dependency, run poetry add {dependency}. If the dependency should be only available for development user append -G dev to the command.

Github Actions

To enable Continuous Integration through Github Actions, we provide a proj_main.yml file. To connect it to Github you need to rename it to main.yml and move it to the .github/workflows/ directory.

You can do it with the following commands:

mkdir -p .github/workflows
mv proj_main.yml .github/workflows/main.yml

Deployment

Setup

This project comes with an render.yaml file, which can be used to create an app on Render.com from a GitHub repository.

Before deploying, please make sure you've generated an up-to-date poetry.lock file containing the Python dependencies. This is necessary even if you've used Docker for local runs. Do so by following these instructions.

After setting up the project, you can init a repository and push it on GitHub. If your repository is public, you can use the following button:

Deploy to Render

If you are in a private repository, access the following link replacing $YOUR_REPOSITORY_LINK$ with your repository link.

  • https://render.com/deploy?repo=$YOUR_REPOSITORY_LINK$

Remember to fill the ALLOWED_HOSTS with the URL of your app, the default on Render.com is appname.onrender.com. Replace appname with your Render.com app name.

Configuring Celery

As there aren't free plans for Workers in Render.com, the configuration for Celery workers/beat will be commented by default in the render.yaml. This means celery won't be available by default.

Uncommenting the worker configuration lines on render.yaml will imply in costs.

SendGrid

To enable sending emails from your application you'll need to have a valid SendGrid account and also a valid verified sender identity. After finishing the validation process you'll be able to generate the API credentials and define the SENDGRID_USERNAME and SENDGRID_PASSWORD envvars on Render.com.

These variables are required for your application to work on Render.com since it's pre-configured to automatically email admins when the application is unable to handle errors gracefully.

Sentry

Sentry is already set up on the project. For production, add SENTRY_DSN environment variable on Render.com, with your Sentry DSN as the value.

You can test your Sentry configuration by deploying the boilerplate with the sample page and clicking on the corresponding button.

Sentry source maps for JS files

The render_build.sh script has a step to push Javascript source maps to Sentry, however some environment variables need to be set on Render.com.

The environment variables that need to be set are:

After enabling dyno metadata and setting the environment variables, your next Render.com Deploys will create a release on Sentry where the release name is the commit SHA, and it will push the source maps to it.

Linting

  • Manually with poetry run prospector and npm run lint on project root.
  • During development with an editor compatible with prospector and ESLint.

Pre-commit hooks

  • Run poetry run pre-commit install to enable the hook into your git repo. The hook will run automatically for each commit.
  • Run git commit -m "Your message" -n to skip the hook if you need.

Opinionated Settings

Some settings defaults were decided based on Vinta's experiences. Here's the rationale behind them:

CELERY_ACKS_LATE = True

We believe Celery tasks should be idempotent. So for us it's safe to set CELERY_ACKS_LATE = True to ensure tasks will be re-queued after a worker failure. Check Celery docs on "Should I use retry or acks_late?" for more info.

Features Catalogue

Frontend

  • react for building interactive UIs
  • react-dom for rendering the UI
  • react-router for page navigation
  • webpack for bundling static assets
  • webpack-bundle-tracker for providing the bundled assets to Django
  • Styling
    • bootstrap for providing responsive stylesheets
    • react-bootstrap for providing components built on top of Bootstrap CSS without using plugins
    • sass for providing compatibility with SCSS files
  • State management and backend integration
    • axios for performing asynchronous calls
    • cookie for easy integration with Django using the csrftoken cookie
    • @reduxjs/toolkit for easy state management across the application with the whole toolkit including devtools for inspecting and debugging Redux via browser and ability to run thunks for interacting with the Redux store through asynchronous logic
    • connected-react-router for integrating Redux with React Router
    • history for providing browser history to Connected React Router
    • react-redux for integrating React with Redux
    • Utilities
    • lodash for general utility functions
    • classnames for easy working with complex CSS class names on components
    • prop-types for improving QoL while developing providing basic type-checking for React props
    • react-refresh for improving QoL while developing through automatic browser refreshing

Backend

  • django for building backend logic using Python
  • djangorestframework for building a REST API on top of Django
  • django-webpack-loader for rendering the bundled frontend assets
  • django-js-reverse for easy handling of Django URLs on JS
  • psycopg2 for using PostgreSQL database
  • sentry-sdk for error monitoring
  • python-decouple for reading environment variables on settings files
  • celery for background worker tasks
  • django-debreach for additional protection against BREACH attack
  • whitenoise and brotlipy for serving static assets

Contributing

If you wish to contribute to this project, please first discuss the change you wish to make via an issue.

Check our contributing guide to learn more about our development process and how you can test your changes to the boilerplate.

Commercial Support

alt text

This project is maintained by Vinta Software and is used in products of Vinta's clients. We are always looking for exciting work, so if you need any commercial support, feel free to get in touch: [email protected]

More Repositories

1

django-templated-email

Django module to easily send templated emails using django templates, or using a transactional mail provider (mailchimp, silverpop, etc.)
Python
680
star
2

django-role-permissions

A django app for role based permissions.
Python
650
star
3

python-linters-and-code-analysis

Python Linters and Code Analysis tools curated list
505
star
4

tapioca-wrapper

Python API client generator
Python
344
star
5

python-api-checklist

Useful checklist for building good Python library APIs, based on "How to make a good library API" PyCon 2017 talk.
335
star
6

playbook

Vinta's Best Moves Compiled
219
star
7

awesome-django-security

A collection of Django security-related tools and libs.
198
star
8

django-ai-assistant

Integrate AI Assistants with Django to build intelligent applications
Python
196
star
9

drf-rw-serializers

Generic views, viewsets and mixins that extend the Django REST Framework ones adding separated serializers for read and write operations
Python
176
star
10

classy-django-rest-framework

Detailed descriptions, with full methods and attributes, for each of Django REST Framework's class-based views and serializers.
Python
170
star
11

django-zombodb

Easy Django integration with Elasticsearch through ZomboDB Postgres Extension
Python
149
star
12

django-virtual-models

Improve performance and maintainability with a prefetching layer in your Django project
Python
146
star
13

entity-embed

PyTorch library for transforming entities like companies, products, etc. into vectors to support scalable Record Linkage / Entity Resolution using Approximate Nearest Neighbors.
Jupyter Notebook
143
star
14

celery-tasks-checklist

Useful checklist for building great Celery tasks.
117
star
15

django-apps-checklist

Useful checklist for build great Django apps. Feel free to contribute!
104
star
16

django-celerybeat-status

A library that integrates with django admin and shows in a simple GUI when your periodic are going to run next.
Python
100
star
17

deduplication-slides

"1 + 1 = 1 or Record Deduplication with Python" Jupyter Notebook
Jupyter Notebook
83
star
18

django-knowledge-share

The engine behind Vinta's Lessons Learned page.
Python
37
star
19

django-production-launch-checklist

A checklist we use here at Vinta before launching a product we've been working on.
37
star
20

tapioca-facebook

Facebook GraphAPI wrapper using tapioca
Python
28
star
21

checklist-para-propostas-pybr

Checklist para propostas de palestras para Python Brasil
25
star
22

eslint-config-vinta

Vinta's ESLint and Prettier shareable configs.
JavaScript
23
star
23

github-metrics

Script for fetching github metrics for your project.
Python
22
star
24

devchecklists-template

The template to create your checklist on Devchecklists. https://devchecklists.com
22
star
25

hub.rocks

An online jukebox with all the songs from Deezer and YouTube. Built with Django and Angular.
Python
21
star
26

django-pg-tenants

Python
20
star
27

aurorae

🌅 🌇 A tool to generate fixed-width CNAB240 files to perform bulk payments
Python
20
star
28

cookiecutter-tapioca

A cookiecutter template for new tapioca wrappers
Python
19
star
29

GPTBundle

GPTBundle, a React application toolkit, harnesses AI to convert textual content into structured forms and delivers advanced autofill suggestions.
TypeScript
19
star
30

critical-incidents-checklist

Useful checklist for dealing with recovery crisis. Based on the talk "Saving Great Projects" 2017 Python Brasil
18
star
31

production-launch-checklist

A checklist we use here at Vinta before launching a product we've been working on.
16
star
32

tapioca-twitter

Twitter API wrapper using tapioca
Python
16
star
33

safari-samesite-cookie-issue

A Django 2.1 project to reproduce WebKit Bug 188165 and Django Ticket #30250
Python
15
star
34

pull-requests-checklist

Do's and Don'ts for Pull Requests. Improve code quality and review speed.
14
star
35

tapioca-instagram

Python
11
star
36

normalizr-redux-talk

Repository containing demo and resouces for the Normalizr Redux talk
JavaScript
8
star
37

django-psi

Easily integrate Google PageSpeed Insights to your development process - with timeline visualization
Python
8
star
38

pythonwat

Slides of Python WAT talk, see README for interactive version. Or go to http://vintasoftware.github.io/pythonwat/ for the HTML compiled one. PT-BR only for now.
Jupyter Notebook
8
star
39

vinta-design-checklists

Design checklists made by our internal team
7
star
40

high-quality-software-standards-checklists

A checklist we use here at Vinta to ensure high quality software at scale
6
star
41

devchecklists.com-content

devchecklists.com
TypeScript
6
star
42

palestra-normalizacao-django

Exemplos para a palestra "Normalize até machucar, desnormalize até funcionar em Django" da Python Nordeste 2018
Python
6
star
43

vinta-feedback-checklists

Checklists about the feedback process.
6
star
44

django-data-watcher

Python
6
star
45

django-upload-files-straight-to-s3

Example project on how to upload files from the frontend straight to S3 without sending to the server using django
Python
6
star
46

bug-card-creation-checklist

Checklist with what we believe should be written whenever a bug card is written.
5
star
47

django-bug-finder

Python
5
star
48

pr-reviewer-checklist

Set of guidelines for anyone reviewing a PR to make sure it's more civilized and avoid creating a toxic feedback culture
5
star
49

ab-testing-checklist

A checklist we use when creating A/B tests on our projects
5
star
50

tapioca-youtube

Youtube API Wrapper using Tapioca
Python
4
star
51

feature-card-creation-checklist

Checklist on how to best describe on a Trello card what needs to be done in a feature
4
star
52

weekly-meeting-checklist

Checklist to avoid wasting time in meetings, focusing them on sharing knowledge, instead of updates.
4
star
53

trigger.io-tcp

trigger.io module for TCP sockets
Java
4
star
54

dojo

Python
4
star
55

sprint-meeting-checklist

Checklist with preparations we at Vinta do for every sprint meeting we
4
star
56

landing-page-creation-checklist

Checklist of concerns one must have whenever creating a landing page completely dissociated from your original homepage
4
star
57

dedupe-clustering-experiments

Experimenting new types of clustering algorithms for Dedupe library
Jupyter Notebook
4
star
58

tapioca-mailgun

Mailgun API wrapper using tapioca
Python
4
star
59

tapioca-bitbucket

Bitbucket API wrapper using tapioca
Python
3
star
60

django-sass-bower-compressor-example

Python
3
star
61

cordova-toast-plugin

Cordova toast message plugin
Java
3
star
62

celery-persistent-revokes

Celery task revokes are stored on memory or on file. This packages makes possible to easely customize how your revokes are stored (Ex.: Database).
Python
3
star
63

django-stack

Python
2
star
64

feature-development-workflow

Developing a feature is much more than just coding it what was specified. This checklist covers other points that are important for code quality and a smoother hand-off.
2
star
65

tapioca-parse

Parse REST API wrapper using tapioca
Python
2
star
66

github-monitor

Python
2
star
67

react-jest-blog-post

JavaScript
2
star
68

django-linters-talk-demo

Demos for DjangoCon 2017 talk: Preventing headaches with linters and automated checks
Python
2
star
69

user-documentation-checklists

General guidelines on how to build awesome SaaS user documentation!
2
star
70

tapioca-mandrill

Mandrill API wrapper using tapioca
Python
2
star
71

medplum-snippet-catalog

A collection of reusable code snippets and components for Medplum projects.
TypeScript
2
star
72

identity-validation

Project to validate we're actually members of Vinta Software
1
star
73

tapioca-harvest

Harvest wrapper using tapioca
Python
1
star
74

react-flux-example

JavaScript
1
star
75

rise-jupyter-talk

Slides da talk "Fazendo apresentações real-time com Jupyter" da Python Sudeste 2016
OpenEdge ABL
1
star