gem-hunter
Language: Python
Django 5, React, Tailwind 4 with Python 3 and Webpack project boilerplate
A Django project boilerplate/template with a multitude of state-of-the-art libraries and tools. If pairing Django with React is a possibility for your project or spinoff, this is the best solution available. Save time with 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:
react for building interactive UIsreact-dom for rendering the UIreact-router for page navigationwebpack for bundling static assetswebpack-bundle-tracker for providing the bundled assets to Djangotailwind for providing responsive stylesheetsaxios for performing asynchronous callscookie for easy integration with Django using the csrftoken cookieopenapi-ts for generating TypeScript client API code from the backend OpenAPI schemahistory for providing browser history to Connected React Routerlodash for general utility functionsclassnames for easy working with complex CSS class names on componentsreact-refresh for improving QoL while developing through automatic browser refreshingdjango for building backend logic using Pythondjangorestframework for building a REST API on top of Djangodrf-spectacular for generating an OpenAPI schema for the Django REST APIdjango-webpack-loader for rendering the bundled frontend assetsdjango-js-reverse for easy handling of Django URLs on JSdjango-upgrade for automatically upgrading Django code to the target version on pre-commitdjango-guid for adding a unique correlation ID to log messages from Django requestspsycopg for using PostgreSQL databasesentry-sdk for error monitoringpython-decouple for reading environment variables on settings filescelery for background worker tasksdjango-csp for setting the draft security HTTP header Content-Security-Policydjango-permissions-policy for setting the draft security HTTP header Permissions-Policydjango-defender for blocking brute force attacks against loginwhitenoise and brotlipy for serving static assetsSeveral people have leveraged our boilerplate to start spinoffs or to boost their efforts in the challenging pursuit of securing funding. Starting with a solid foundation allows you to create more resilient products and focus on what really matters: discovering and delivering value to your customers. If you are one of those people, we're eager to help you even more! We can spread the word about your project across our social media platforms, giving you access to a broader audience.
Send us an email at contact@vintasoftware.com telling us a bit more about how our boilerplate helped you boost your project.
pip install django, to have the django-admin command availableproject_name with your project name and remove the curly braces):
django-admin startproject {{project_name}} --extension py,json,yml,yaml,toml --name Dockerfile,README.md,.env.example,.gitignore,Makefile,.npmrc --template=https://github.com/vintasoftware/django-react-boilerplate/archive/refs/heads/main.zip
. right after the project name, using the following command:
django-admin startproject {{project_name}} . --extension py,json,yml,yaml,toml --name Dockerfile,README.md,.env.example,.gitignore,Makefile,.npmrc --template=https://github.com/vintasoftware/django-react-boilerplate/archive/refs/heads/main.zip
In the next steps, always remember to replace {{project_name}} with your project's name (in case it isn't yet):
--extension and --name params!cd {{project_name}}ADMINS settings variable in {{project_name}}/backend/{{project_name}}/settings/base.pySERVER_EMAIL to the email address used to send e-mails in {{project_name}}/backend/{{project_name}}/settings/production.pyAfter completing ALL of the above, remove this Project bootstrap section from the project README. Then follow Running below.
local.py settings file:
cp backend/{{project_name}}/settings/local.py.example backend/{{project_name}}/settings/local.py.env.example file:
cp backend/.env.example backend/.envbackend/.env file on a text editor and uncomment the line DATABASE_URL=postgres://{{project_name}}:password@db:5432/{{project_name}}make docker_setupusers app:
make docker_makemigrationsmake docker_migratemake docker_uphttp://localhost:8000 on your browser and the project should be running there
make docker_up, some containers are spinned up (frontend, backend, database, etc) and each one will be running on a different portmake docker_logs <service name> (either backend, frontend, etc)make docker_downpnpm add <package name>
The above command will update your
package.jsonandpnpm-lock.yaml, but won't make the change effective inside the container yet
docker compose run --rm backend 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.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
backend/.env file on a text editor and do one of the following:
DATABASE_URL=sqlite:///db.sqlite3DATABASE_URL=postgres://{{project_name}}:password@db:5432/{{project_name}} in order to make it correctly point to your database URL
postgres://USER:PASSWORD@HOST:PORT/NAMEDATABASE_URL setting for the database you wish to use
DATABASE_URL for commonly used enginesADMIN_ENVIRONMENT_LABEL to the text you want displayed in the Django admin notice (for example Local, Staging, or Production). If omitted, the admin falls back to the current Django settings module name.ADMIN_ENVIRONMENT_COLOR and ADMIN_ENVIRONMENT_BACKGROUND_COLOR to customize the notice colors.poetry installbackend directoryusers app:
poetry run python manage.py makemigrationspoetry run python manage.py migratepoetry run python manage.py spectacular --color --file schema.ymlpoetry run python manage.py runserverpnpm installpnpm run openapi-ts
pnpm run dev
http://localhost:8000 to see the project runningpoetry run celery --app={{project_name}} worker --loglevel=inforedis-server --port 6379 to start the Redis server.CELERY_BROKER_URL environment variable in the backend/.env file to redis://localhost:6379/0.
/0 at the end of the URL specifies the database number on the Redis server. Redis uses a zero-based numbering system for databases, so 0 is the first database. If you don't specify a database number, Redis will use the first database by default.The project expects Mailhog SMTP server to be running on port 1025, you may alter that by changing
EMAIL_PORTon settings
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
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.
We use the DRF-Spectacular tool to generate an OpenAPI schema from our Django Rest Framework API. The OpenAPI schema serves as the backbone for generating client code, creating comprehensive API documentation, and more.
The API documentation pages are accessible at http://localhost:8000/api/schema/swagger-ui/ or http://localhost:8000/api/schema/redoc/.
Important
Anytime a view is created, updated, or removed, the schema must be updated to reflect the changes. Failing to do so can lead to outdated client code or documentation.
To update the schema, run:
make docker_backend_update_schemapoetry run python manage.py spectacular --color --file schema.ymlWe use the openapi-ts tool to generate TypeScript client code from the OpenAPI schema. The generated client code is used to interact with the API in a type-safe manner.
Important
Anytime the API schema is updated, the client code must be regenerated to reflect the changes. Failing to do so can lead to type errors in the client code.
To update the client code, run:
make docker_frontend_update_apipnpm run openapi-tsNote
If pre-commit is properly enabled, it will automatically update both schema and client before each commit whenever necessary.
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
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:
If you are in a private repository, access the following link replacing $YOUR_REPOSITORY_URL$ with your repository link.
https://render.com/deploy?repo=$YOUR_REPOSITORY_URL$Keep reading to learn how to configure the prompted environment variables.
Chances are your project name isn't unique in Render, and you'll get a randomized suffix as your full app URL like: https://{{project_name}}-a1b2.onrender.com.
But this will only happen after the first deploy, so you are not able to properly fill ALLOWED_HOSTS yet. Simply set it to * then fix it later to something like {{project_name}}-a1b2.onrender.com and your domain name like example.org.
Default is 1, meaning the build script will run collectstatic during deploys.
Default is 1, meaning the build script will run collectstatic during deploys.
Django requires a SECRET_KEY that is at least 50 characters long and with enough randomness. Render’s generateValue: true produces a shorter value (about 44 characters) that does not meet Django’s security check, so it fails with security.W009.
The correct approach is to declare the variable with sync: false. That way, the SECRET_KEY is not stored in the repository, and the first time the Blueprint is created, Render will prompt you to provide the secret value manually. This ensures the key is long, random, and secure while keeping it outside version control.
You can generate a new key by running the following command on your local machine:
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"Set this to a short label such as Production, Staging, or Review App. The value is rendered as a persistent notice above the Django admin so staff users can immediately see which environment they are changing.
Controls the notice text color. Defaults to #111827.
Controls the notice background color. Defaults to #f59e0b.
By default, the project will always run the render_build.sh script during deployments. This script does the following:
collectstaticAs 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.
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 environment variables 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.
Media files integration with S3 or similar is not supported yet. Please feel free to contribute!
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.
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:
SENTRY_ORG - Name of the Sentry Organization that owns your Sentry Project.SENTRY_PROJECT_NAME - Name of the Sentry Project.SENTRY_API_KEY - Sentry API key that needs to be generated on Sentry. You can find or create authentication tokens within Sentry.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.
poetry run ruff and pnpm run lint on project root.poetry run pre-commit install to enable the hook into your git repo. The hook will run automatically for each commit.Some settings defaults were decided based on Vinta's experiences. Here's the rationale behind them:
Using atomic requests in production prevents several database consistency issues. Check Django docs for more details.
Important: When you are queueing a new Celery task directly from a Django view, particularly with little or no delay/ETA, it is essential to use transaction.on_commit(lambda: my_task.delay()). This ensures that the task is only queued after the associated database transaction has been successfully committed.
transaction.on_commit is not utilized, or if a significant delay is not set, you risk encountering race conditions. In such scenarios, the Celery task might execute before the completion of the request's transaction. This can lead to inconsistencies and unexpected behavior, as the task might operate on a database state that does not yet reflect the changes made in the transaction. Read more about this problem on this article.CELERY_TASK_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.Django-CSP helps implementing Content Security Policy (CSP) in Django projects to mitigate cross-site scripting (XSS) attacks by declaring which dynamic resources are allowed to load.
In this project, we have defined several CSP settings that define the sources from which different types of resources can be loaded. If you need to load external images, fonts, or other resources, you will need to add the sources to the corresponding CSP settings. For example:
CSP_SCRIPT_SRC.CSP_IMG_SRC.Please note that you should only add trusted sources to these settings to maintain the security of your site. For more details, please refer to the Django-CSP documentation.
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.
This project is maintained by Vinta Software and is used in products of Vinta's clients. We are always looking for exciting work! If you need any commercial support, feel free to get in touch: contact@vinta.com.br
