Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lordsarcastic/djangoer

A production-ready template for Django applications
https://github.com/lordsarcastic/djangoer

backend django django-project django-rest-framework template-repository

Last synced: about 2 months ago
JSON representation

A production-ready template for Django applications

Awesome Lists containing this project

README 

        
# djangoer

A production-ready template for Django applications



## Introduction

This Django template was created out of a need for consistent structure for projects with a setup that's easy to understand and use with as minimal additional setup as possible.



### How to use

Three commands and you're good to go:

- `cp .env.example .env`

- `make build`

- `make up`



A much detailed explanation is in the [How to use (fleshed-out)](#how-to-use-fleshed-out) section.



## Features

- Uses standard Django application structure. No folder complexities to be navigated through.

- Drop-in template, two commands and you have all the features at your fingertips: `make build && make up`

- Built-in simple Docker set up that just works!

- Support for .env files and typed environmental variables using Pydantic. Try running your application without needed environment variables and it crashes immediately, fail-fast without future tears.

- First class support for Postgres. Just add `DATABASE_URL` in your `.env` file.

- Uses lightning fast Ruff for both formatting and linting. Drop-in replacement for Black and Isort and 10 - 100x faster too!

- Easy way to run commands using `make`. Run migrations with `make migrate`, start application with `make up`. No need to memorize verses of commands.

- Included GitHub workflow for running tests

- Environment based settings file

- Everything you need to start implementing your first API.



### What is hoped to be achieved

- Simplicity; no need for bloated classes and huge utils that you'll likely never use. Everything here should be very much needed in most projects

- Low barrier for entry; a template that is easy to start with and does not seem too advanced for beginners to use

- Production-ready; the above does not remove the important fact that this should be always production-ready without obvious faults

- Consistency; a smell for codebases is you not having a 'knowing' of where certain code is located. A wanted structure is one that's easy to navigate



### What is not hoped to be achieved

- Utility dump; this template will not be where all sorts of utilities are dumped because, 'why not?'.

- I'm out of points, sorry. This kind of stuff should be like 3 points or so, but then...



## How to use (Fleshed out)

### Requirements:

- Make, Docker and Docker Compose



### Running the application with Docker (recommended)

- Clone the repo

- `cd` into the repo

- Duplicate the file named ".env.example", rename the new copy to ".env".

- Edit the content of the `.env` file as you want. At this point you'll also want to edit the

`environment` section of the `postgres` service in the `docker-compose.yml` file to

reflect your choice of database. Ensure you correlate this change with the content

of the `.env` file.

- Perform migrations with `make migrate`

- Create your superuser account with `make createsuperuser`. Fill in required details. Note that your password won't display on the screen. Type blindly and trust everything to work.

- To start the server, run `make up`

- You can start making requests by visiting [http://127.0.0.1:8000](http://127.0.0.1:8000)

- Edit the template as you want for your app



### Running the application outside of Docker (not recommended, not even remotely)

- Create a database with Postgres through the `psql` command. Can't remember

the whole steps and I'm too tired to google it, it's why I said you should

use Docker.

- Duplicate the file named ".env.example", rename the new copy to ".env".

- Edit the content of the `.env` file as you want, especially to

reflect your choice of database. Ensure you correlate this change with the results of

of the first step

- Perform migrations with `python manage.py migrate`. You still don't want to use Docker?!

- To start the server, run `gunicorn --bind 0.0.0.0:8000 config.wsgi:application`.

Lol, I told you to use Docker.

- You can start making requests by visiting [http://127.0.0.1:8000](http://127.0.0.1:8000)

- Edit the template as you want for your app (switch to Docker)



## Glossary

This section contains a list of commonly needed helps while working on this project.



Majority of the commands you'll need are in the Makefile and can be run as:

```

make 

```



### All needed commands currently in the Makefile

- up: start up the containers

- bash: starts a bash shell for the application

- build: builds the containers only

- build-up: builds and starts the containers

- createsuperuser: spawns the Django app to create a superuser

- down: stops the containers

- format: runs isort and black on the codebase to make it fine

- flush-db: empties the database and begins the DB from scratch

- install: installs all dependencies in a virtual env locally

- lint: runs ruff to sort import and format the code

- migrations: creates migrations based on DB schema

- migrate: runs the created migrations

- resetdb: resets the database, deletes everything including the database itself

- run-command: runs a command in the Django app context. For example, `make run-command command="python manage.py test"`

- shell: spawns a shell within the Django app context. The same as `manage.py shell`.

- test: runs the test suite using pytest

- testcase: runs a single test case. For example, `make testcase testcase="tests/test_models.py::TestUserModel::test_user_can_be_created"`

- up-d: starts up the container without logs



### How do I run commands in Docker?

First check the list above if the command you need is there. If it is, you can run it as `make `. For example, to run tests, I can do: `make test`. If it isn't, continue reading.



Ideally, you should be using `make run-command command=""`. For example, to run tests, I can do: `make run-command command="python manage.py test"`.



However, if you're not using make, you can run commands in Docker using the syntax: `docker compose run  `. For example, to run tests, I can do: `docker compose run web python manage.py test`.



### How do I enable auto-imports for libraries on VSCode

- Outside of docker, run `make install`

- Start a virtual environment in the root folder by running `pipenv shell`

- On your VSCode, at the bottom right corner, you'll see a Python version, click on it and select the Python interpreter created from your virtual environment.

You can continue your work inside docker.



## Change Log

### 31-01-2023

- Initial release

- Added support for Postgres

- Added support for .env files

- Added support for typed environmental variables using Pydantic

- Added Docker support



### 20-02-2023

- Added Make command for formatting and linting



### 13-01-2024

- Added auto removal of containers when running one-off commands



### 24-01-2024

- Trim down Dockerfile to reduce needless steps and upgrade python version

- Added extensions for resetting db

- Added command to run any command on app shell

- Replaced test runner with pytest

- Renamed `makemigrations` command to `migrations`

- Removed black and ruff

- Upgraded pydantic

- Replaced linter and formatter with ruff

- Bumped Python version to 3.12

- Added environment based settings file

- Added changelog



## Got problems?

Raise an issue.



## FAQs

1.

    Q: Why do you insist I use Docker?



    A: It is actually easier to use and setup

    than the alternative. You can also easily

    switch to the alternative if you want to.