Django Coleman: A very simple Task Management web app written with Django Admin.
- Simple task manager that allows to define a tasks with title, partner (customer, provider...), description, responsible of the task, priority...
- Each task may have items: sub-tasks to be done.
- The built-in Django Authentication and Authorization system to manage users and groups, login, etc.
- Module django-adminfilters that allows multiselection searches.
- Send emails when a task is created.
- Spanish translations.
- Basic Rest API configuration (disabled by default, check the
- Optionally, you can use Django Coleman along with Django Coleman Viewer to allows users to follow the orders.
- Pytest with some tests as example and code coverage reports configured.
- Docker and Docker Compose configurations (images published in Docker Hub).
- Ready to use "production" configurations as reference.
- Python 3.6+ (tested with Python 3.6 and 3.10).
- Django 3.2 LTS and other dependencies declared in
requirements.txtfile (use virtual environments or containers!).
- A Django compatible database like PostgreSQL (by default uses the Python's built-in SQLite database for development purpose).
Install and Run
Using Docker, check the section below. Otherwise:
Create a virtual environment and activate it with (Optional):
$ python3 -m venv .venv && source .venv/bin/activate
Install dependencies with:
$ pip install --upgrade pip wheel $ pip install -r requirements.txt
Create the database with:
$ python3 manage.py makemigrations $ python3 manage.py makemigrations partner mtasks $ python3 manage.py migrate
To create an admin user:
$ python3 manage.py createsuperuser
Then run in development mode with:
$ python3 manage.py runserver
Add at the end
0:5000 if you want to open the port 5000
instead of the default 8000, and the
0: prefix is to
let Django accepts connection outside localhost (optional).
Or use the following script to startup in "production" mode, with a uWSGI server:
$ uwsgi uwsgi.ini
Procfile and Honcho
Honcho has the advantage of loading the environment variables
from an .env file automatically (see section below). To install
pip3 install honcho. Once installed, to run
the app with Honcho:
$ honcho start web
There are other shortcuts in the Procfile, like a command to create both the user and database (you have to provide the "master" password from the user "postgres" in an env variable):
$ POSTGRES_PASSWORD=postgres honcho start createdb
And here is the command to automatically creates an "admin" user with password "admin1234":
$ honcho start createadmin
First, copy the
.env.example file as
.env file, and edit whatever
value you want to:
$ cp .env.example .env
Then before run for the first time the containers, you have to either download the images from Docker Hub or build them from the source code. To build the images from the source code, execute:
$ docker-compose build
Or to get the images from Docker Hub, execute:
$ docker-compose pull
Once the images are installed in your local machine, create the containers and run all of them with:
$ docker-compose up
The first time it runs some errors about the DB are shown, that's because you need to create the DB and the structure (tables, indexes), all can be created in another terminal executing:
$ docker-compose run django-coleman-provision
Even a user
admin with password
admin1234 is created.
Access the apps and the DB
The URL to access the app is the same than running it with Python locally: http://localhost:8000/admin/ .
Once created an order, if the id is
1, it can be viewed
by the viewer with http://localhost:8888/1?t=porgs .
If you want to then open a psql session for the DB from the
docker-compose run psql.
By default a local volume
django-coleman_data is attached
to the Postgres container so even executing
won't delete the data, but if you want to start from scratch:
$ docker-compose down $ docker volume rm pg-coleman_data
Add changes in the code
When adding changes in the code, the image needs to be updated:
$ docker-compose build
Then run again. A script
docker-build.sh with more advance
features and without using docker-compose is also provided
to re-build the image.
Most settings can be overwritten with environment variables. For example to overwrite the language translations of the application and set debug options to false:
$ DEBUG=False LANGUAGE_CODE=es-ar python3 manage.py runserver
Also in development environments an
.env file can be used to setup
the environment variables easily, checkout the .env.example as example.
You can copy the example file and edit the variables you want to change:
$ cp .env.example .env $ vi .env
Some available settings:
DEBUG: set the Django
UTC. Other example:
en-us. Other example:
SITE_HEADER: Header title of the app. Default to "Django Coleman - A Simple Task Manager".
DATABASE_URL: Database string connection. Default uses SQLite database. Other example:
- More settings like email notifications, check the
settings.pyfile for more details, any variable that is set with
env('...is able to be configured using environment variables.
To run in a production environment, check the README-production.rst notes, or see the official Django documentation.
Access the application
Like any Django app developed with Django Admin, enter with: http://localhost:8000/admin
Tests run with Pytest:
Or use the Honcho task that also generates a report with
the tests coverage:
honcho start --no-prefix test.
Django Coleman Viewer
Django Coleman Viewer is a small webapp that can be used along with Django Coleman to allow "partners" (customers, employees, providers...) to see their orders anonymously, without access to the Django Admin.
You need to enable the email notifications and set
True to send the emails with the viewer order URL. See more configurations in the
coleman/settings_emails.py file, and checkout the viewer project.
Some tips if you are improving this application.
After add to the source code new texts to be translated, in the command
line go to the module folder where the translations were edited, e.g.
the "mtasks" folder, and execute the following replacing
by a valid language code like
$ django-admin makemessages -l LANG
Then go to the .po file and add the translations. In the
case of the "mtasks" module with
es language, the file is
execute the following to compile the locales:
$ django-admin compilemessages
Oldest Django versions
master branch works with Django 3.2 LTS. The are a few more branches (though unmaintained):
With the source code that works for each version of Django, and maybe tweaking some configurations can works with older versions too.
Authors: (2017-2022) Mariano Ruiz <email@example.com>