Installation¶

Install¶

Cloud Browser can be installed from PyPI or from GitHub.

PyPi¶

Basic installation:

pip install django-cloud-browser

Versioned¶

Install a specific version (where <VERSION> is something like “0.5.4”) from PyPi:

pip install django-cloud-browser==<VERSION>

or from GitHub:

pip install https://github.com/ryan-roemer/django-cloud-browser/zipball/v<VERSION>

Development¶

Install the Cloud Browser package from current development source:

pip install https://github.com/ryan-roemer/django-cloud-browser/tarball/master

or:

pip install -e git://github.com/ryan-roemer/django-cloud-browser#egg=cloud_browser

Software Requirements¶

Cloud Browser uses conditional imports to only actually require other libraries that are used in the active configuration. Loosely speaking, for deployment, only the following is actually needed:

Python 2.7 or Python 3.6
Django

The application relies on third party open source libraries to actually communicate with cloud datastores, so for each cloud datastore you need the corresponding library below:

Apache Libcloud: apache-libcloud
Amazon S3 / Google Storage (deprecated): boto
Rackspace Cloud Files / OpenStack Storage (deprecated): cloudfiles (version 1.7.4+ is required).

Configuration¶

All configuration options are fully described in the application settings documentation.

Here is a quick start example for Rackspace Cloud Files:

Settings¶

First, start with edits to your Django project’s settings.py:

INSTALLED_APPS = (
    # ...
    'cloud_browser',
)

CLOUD_BROWSER_DATASTORE = "ApacheLibcloud"
CLOUD_BROWSER_APACHE_LIBCLOUD_PROVIDER = "OPENSTACK_SWIFT"
CLOUD_BROWSER_APACHE_LIBCLOUD_ACCOUNT = "<my_account>"
CLOUD_BROWSER_APACHE_LIBCLOUD_SECRET_KEY = "<my_secret_key>"

In addition, for more security options, the following Cloud Browser options may be set via environment variables instead of settings.py variables:

CLOUD_BROWSER_APACHE_LIBCLOUD_PROVIDER
CLOUD_BROWSER_APACHE_LIBCLOUD_ACCOUNT
CLOUD_BROWSER_APACHE_LIBCLOUD_SECRET_KEY
CLOUD_BROWSER_AWS_ACCOUNT (deprecated)
CLOUD_BROWSER_AWS_SECRET_KEY (deprecated)
CLOUD_BROWSER_GS_ACCOUNT (deprecated)
CLOUD_BROWSER_GS_SECRET_KEY (deprecated)
CLOUD_BROWSER_RACKSPACE_ACCOUNT (deprecated)
CLOUD_BROWSER_RACKSPACE_SECRET_KEY (deprecated)
CLOUD_BROWSER_RACKSPACE_SERVICENET (deprecated)
CLOUD_BROWSER_RACKSPACE_AUTHURL (deprecated)

in the form of:

$ export CLOUD_BROWSER_<Setting Name>="<value>"

Other settings you may wish to investigate include:

Container white/black lists: Control access to containers.
- CLOUD_BROWSER_CONTAINER_WHITELIST
- CLOUD_BROWSER_CONTAINER_BLACKLIST
CLOUD_BROWSER_DEFAULT_LIST_LIMIT: Default number of objects to display per browser page.

URLs¶

Next, add the URLs to your urls.py:

urlpatterns = patterns('',
    # ...
    url(r'^cb/', include('cloud_browser.urls')),
)

Admin Configuration¶

Cloud Browser also supports integration with the Django admin, for cases in which only admin users get to access the datastore. Separate templates, as well as built-in Django admin resources are used for a consistent admin experience.

Note

This is not a “full” Django application, just a modest hack (with some JavaScript trickery) to make the Cloud Browser appear like a normal administrative application. And, unfortunately there is no link off the admin index page (although you could extend the Django admin index template to include this without too much hassle).

Settings¶

In addition to the general settings above, the settings variable CLOUD_BROWSER_VIEW_DECORATOR should be set to staff_member_required to match the rest of the administrative permissions:

from django.contrib.admin.views.decorators import staff_member_required
CLOUD_BROWSER_VIEW_DECORATOR = staff_member_required

Alternatively, a fully-qualified string path can be used like:

CLOUD_BROWSER_VIEW_DECORATOR = \
    "django.contrib.admin.views.decorators.staff_member_required"

URLs¶

Cloud Browser has a separate set of templates and URLs for use in with the admin. Here’s a suggested setup:

urlpatterns = patterns('',
    # ...

    # Place Cloud Browser URLs **before** admin.
    url(r'^admin/cb/', include('cloud_browser.urls_admin')),

    # Admin URLs.
    url(r'^admin/', include(admin.site.urls)),
)

Static Media¶

The Cloud Browser application relies on a modest amount of CSS and JavaScript. By default, the static media is served by a Django static view, as this is the most compatible approach (and has no further configuration).

However, this is not efficient, as the static media files should be separately statically served. If you separately serve the Cloud Browser static media directory, the application will use links instead of inline code dumps. To enable this, simply symlink the Cloud Browser static media directory to wherever your static media is served from (in this case “/path/to/static_media” is the MEDIA_ROOT):

$ cd /path/to/static_media
$ ln -s /path/to/cloud_browser/templates/cloud_browser_media cloud_browser

(in this case a “cloud_browser” symlink), and then add the relative path from your MEDIA_ROOT to the following settings.py variable:

CLOUD_BROWSER_STATIC_MEDIA_DIR = "cloud_browser"

And all of the Cloud Browser media is actually statically served.

Examples¶

The source contains an example project that is configures and serves up the Cloud Browser application, and little more. It is a good starting point if you are having difficulties getting things going.

Docker¶

The example project can also be used as a quick ad-hoc explorer for cloud storage systems by running it in Docker:

docker run \
  -p 8000:8000 \
  -e CLOUD_BROWSER_DATASTORE="ApacheLibcloud" \
  -e CLOUD_BROWSER_APACHE_LIBCLOUD_PROVIDER="OPENSTACK_SWIFT" \
  -e CLOUD_BROWSER_APACHE_LIBCLOUD_ACCOUNT="<my_account>" \
  -e CLOUD_BROWSER_APACHE_LIBCLOUD_SECRET_KEY="<my_secret_key>" \
  cwolff/django-cloud-browser:latest