Installation¶
You can run django-ca as a regular app in any existing Django project of yours, but if you don’t have any Django project running, you can run it as a standalone project.
Requirements¶
- Python 2.7 or Python 3.4+
- Django 1.8+
- Any database supported by Django (sqlite3/MySQL/PostgreSQL/...)
- Python, OpenSSL and libffi development headers
As Django app (in your existing Django project)¶
This chapter assumes that you have an already running Django project and know how to use it.
You need various development headers for pyOpenSSL, on Debian/Ubuntu systems, simply install these packages:
$ apt-get install gcc python3-dev libffi-dev libssl-dev
You can install django-ca simply via pip:
$ pip install django-ca
and add it to your INSTALLED_APPS
:
INSTALLED_APPS = [
# ... your other apps...
'django_ca',
]
... and configure the other available settings to your liking, then simply run:
$ python manage.py migrate
$ python manage.py collectstatic
# FINALLY, create the root certificates for your CA:
# (replace parameters after init_ca with your local details)
$ python manage.py init_ca RootCA \
> /C=AT/ST=Vienna/L=Vienna/O=Org/OU=OrgUnit/CN=ca.example.com
After that, django-ca should show up in your admin interface (see Web interface) and
provide various manage.py
commands (see Command-line interface).
As standalone project¶
You can also install django-ca as a stand-alone project, if you install it via git. The project provides a command-line interface that provides complete functionality. The web interface is optional.
Note
If you don’t want the private keys of your CAs on the same machine as the web interface, you can also host the web interface on a second server that accesses the same database (CA private keys are hosted on the filesystem, not in the database). You obviously will not be able to sign certificates using the web interface, but you can still e.g. revoke certificates or run a OCSP responder.
In the following code-snippet, you’ll do all necessary steps to get a basic setup:
# install dependencies (adapt to your distro):
$ apt-get install gcc git python3-dev libffi-dev libssl-dev virtualenv
# clone git repository:
$ git clone https://github.com/mathiasertl/django-ca.git
# create virtualenv:
$ cd django-ca
$ virtualenv -p /usr/bin/python3 .
$ source bin/activate
# install Python dependencies:
$ pip install -U pip setuptools
$ pip install -r requirements.txt
In the above script, you have created a virtualenv, meaning that all
libraries you install with pip install
are installed in the virtualenv (and
don’t pollute your system). It also means that before you execute any
manage.py
commands, you’ll have to activate your virtualenv, by doing, in
the directory of the git checkout:
$ source bin/activate
Configure django-ca¶
Before you continue, you have to configure django-ca. Django uses a file called
settings.py
, but so you don’t have to change any files managed by git, it includes
localsettings.py
in the same directory. So copy the example file and edit it with your
favourite editor:
$ cp ca/ca/localsettings.py.example ca/ca/localsettings.py
The most important settings are documented there, but you can of course use any setting provided by Django.
Warning
The SECRET_KEY
and DATABASES
settings are absolutely mandatory. If you use the
Web interface, the STATIC_ROOT
setting is also mandatory.
Initialize the project¶
After you have configured django-ca, you need to initialize the project by running a few
manage.py
commands:
$ python ca/manage.py migrate
# If you intend to run the webinterface (requires STATIC_ROOT setting!)
$ python ca/manage.py collectstatic
# FINALLY, create a certificate authority:
# (replace parameters after init_ca with your local details)
$ python manage.py init_ca /C=AT/ST=Vienna/L=Vienna/O=Org/CN=ca.example.com
Please also see Certificate authority management for further information on how to create certificate
authorities. You can also run init_ca
with the -h
parameter for available arguments.
Create manage.py shortcut¶
If you don’t want to always chdir to the git checkout, activate the virtualenv
and only then run manage.py
, you might want to create a shortcut shell
script somewhere in your PATH
(e.g. /usr/local/bin
):
#!/bin/bash
# BASEDIR is the location of your git checkout
BASEDIR=/usr/local/share/ca
PYTHON=${BASEDIR}/bin/python
MANAGE=${BASEDIR}/ca/manage.py
${PYTHON} ${MANAGE} "$@"
Setup a webserver¶
Setting up a webserver and all that comes with it is really out of scope of
this document. The WSGI file is located in ca/ca/wsgi.py
. Django itself
provides some info for using Apache and mod_wsgi,
or you could use uWSGI and nginx,
or any of the many other options available.
Apache and mod_wsgi¶
Github user Raoul Thill notes that you need some special configuration variable if you use Apache together with mod_wsgi (see here):
WSGIDaemonProcess django_ca processes=1 python-path=/opt/django-ca/ca:/opt/django-ca/ca/ca:/opt/django-ca/lib/python2.7/site-packages threads=5
WSGIProcessGroup django_ca
WSGIApplicationGroup %{GLOBAL}
WSGIScriptAlias / /opt/django-ca/ca/ca/wsgi.py
Regular cronjobs¶
Some manage.py
commands are intended to be run as cronjobs:
# assuming you cloned the repo at /root/:
HOME=/root/django-ca
PATH=/root/django-ca/bin
# m h dom mon dow user command
# notify watchers about certificates about to expire
* 8 * * * root python ca/manage.py notify_expiring_certs
# recreate the CRL and the OCSP index
12 * * * * root python ca/manage.py dump_crl
14 * * * * root python ca/manage.py dump_ocsp_index