1. django-chartwerk is written to save charts to Amazon Web Service’s Simple Storage Service (S3). We assume that’s your plan, too.
  2. django-chartwerk uses Django’s JSONField field, therefore, the app requires a PostgreSQL database ≥ 9.4.


If you’re not already using PostgreSQL in a project you’d like to add django-chartwerk to, you can separate django-chartwerk’s database from your default database by using a custom router, as outlined in the Django documentation. See “Using a database router” for an example.


  1. Install django-chartwerk using pip.
$ pip install django-chartwerk
  1. Add Chartwerk’s dependencies and the minimum configuration variables.
# project/

    # ...



Just trying out Chartwerk locally? Set the above CHARTWERK_ variables to gibberish. They’re only needed when you start publishing charts but will throw errors if they aren’t set.

  1. Add Chartwerk to your project’s
# project/

urlpatterns = [
  # ...
  url(r'^chartwerk/', include('chartwerk.urls')),
  1. Chartwerk uses Celery to process some tasks asynchronously. Read “First steps with Django” to see how to setup a Celery app in your project. Here is a configuration you can also use to start:
# project/
import os

from celery import Celery
from django.conf import settings

os.environ.setdefault('DJANGO_SETTINGS_MODULE', '<your project>.settings')

app = Celery('chartwerk')
app.config_from_object('django.conf:settings', namespace='CELERY')
# Use synchronous tasks in local dev
if settings.DEBUG:
app.autodiscover_tasks(lambda: settings.INSTALLED_APPS, related_name='celery')

# project/
from .celery import app as celery_app

__all__ = ['celery_app']
  1. Run chartwerk migrations and load free chart templates from fixtures.
$ python migrate chartwerk
$ python loaddata free_charts
  1. Start the dev server and enjoy!
$ python runserver


The default permissions setting for Chartwerk’s backend requires that users are authenticated. So in a new project with DEBUG = true, an unauthenticated user can access the Editor, but she cannot save a chart to the backend (403 error).

For new projects, then, be sure to create a user account and login before trying to save charts.

Using a database router

If you’d like to separate django-chartwerk’s PostgreSQL database from the database(s) used in the rest of your Django project, you can write and connect a router.

For example:

# project/
class ChartwerkRouter(object):
  def db_for_read(self, model, **hints):
    if model._meta.app_label == 'chartwerk':
      return 'chartwerk'
      return 'default'

  def db_for_write(self, model, **hints):
    if model._meta.app_label == 'chartwerk':
      return 'chartwerk'
      return 'default'

  def allow_relation(self, obj1, obj2, **hints):
    if obj1._meta.app_label == 'chartwerk' or obj2._meta.app_label == 'chartwerk':
      return True
    return None

  def allow_migrate(self, db, model):
    if db == 'chartwerk':
      return model._meta.app_label == 'chartwerk'
    elif model._meta.app_label == 'chartwerk':
      return False
    return None

Add your router and database in settings.

# project/
import dj_database_url

# Add chartwerk DB to existing DB settings
DATABASES['chartwerk'] = dj_database_url.parse('postgres://...')

When you separate django-chartwerk’s database, you must specify the database explicitly when running migrations to create models and loading fixtures.

$ python migrate chartwerk --database chartwerk
$ python loaddata free_charts --database chartwerk