If you haven't tried the IPython Notebook yet, you're missing out on a very neat tool. I just started using it a few days ago myself and I regret not having used it much sooner.

I'm currently working on a new Django project where I need to use Amazon's MWS API. I find myself using the Django shell a lot to experiment with the API while building the app. While the IPython shell is quite nice, the IPython Notebook is just way better!

The IPython Notebook allows me to add notes in Markdown format in different sections, split up code execution and reference their outputs, move the sections around, use auto-complete, and it even works with ipdb. And those are just the basic stuff, I haven't even looked at the more advance features yet!

Anyway, enough talking and let's get you started. Note that in the instructions below, I'm assuming you have your Python packages directory mapped somewhere for persistent storage (like a host volume or data container) and you run the Django runserver on port 80.

Make sure you have the latest version of 'pip'

$ docker-compose run my_django_service pip install --upgrade pip

Install 'django-extensions' and 'ipython[notebook]'

$ docker-compose run my_django_service pip install django-extensions ipython[notebook]

In your project repo, create a file called 'ipython_config.py' in the same directory as the 'manage.py' file with this content

# ipython_config.py

c = get_config()

# Allow all IP addresses to use the service and run it on port 80.
c.NotebookApp.ip = '0.0.0.0'
c.NotebookApp.port = 80

# Don't load the browser on startup.
c.NotebookApp.open_browser = False

Enter the bash shell of the container

$ docker-compose run --service-ports my_django_service bash

Note: Normally, I would just run the command here directly. But there appears to be a bug causing the kernel to keep dying unless you enter the shell first. Also note here that we're using the --service-ports option to expose the container ports so we can access the service from the host's web browser.

Inside the container, run the 'shell_plus' command with '--notebook' (from django-extensions)

$ python manage.py shell_plus --notebook

You can now access the IPython Notebook service at http://localhost and create "Django Shell-Plus" notebooks!

Important security notice for Linux users

Since we're allowing the IPython Notebook to accept connections from all IP addresses, this could be a major security risk if your container contains sensitive data.

For example, if you're at Starbucks and using their public WiFi, everyone in that cafe can access your IPython Notebook service!

I highly recommend to set firewall rules to block access. Below are iptables rules I set on my laptop running Ubuntu 14.04.

$ sudo iptables -I FORWARD -i eth0 -j DROP
$ sudo iptables -I FORWARD -i wlan0 -j DROP

$ sudo iptables -I FORWARD -i eth0 -m state --state ESTABLISHED -j ACCEPT
$ sudo iptables -I FORWARD -i wlan0 -m state --state ESTABLISHED -j ACCEPT

We set the FORWARD rules because the packets we want to block are forwarded to the Docker container.

We accept ESTABLISHED states so associated connections are not blocked (for example, in my case, I run a code that connects to the Amazon service and I need the response to be able to reach the Docker container).

Note that if you restart your machine, these rules get erased. To make sure the rules are saved, install the iptables-persistent package.

$ sudo apt-get update && sudo apt-get install iptables-persistent

During installation, you will get prompted if you want to save your existing rules.

If you make changes after the initial installation, you can save again using this command:

sudo invoke-rc.d iptables-persistent save

More iptables info here.