Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!




Homunculus aims to provide a unified interface to deploy python web applications on standartized environments.

Developers of WSGI-Applications specify the needed infrastructure in a config file, and then create packages. These packages can then be run, without further configuration, on every homunculus server. The necessary infrastructure will be provided automatically. Locally, they can be run with the homunculus development server.

Things that can be specified as infrastructuctural dependency include

  • MySQL databases
  • SQLite databases
  • Memcached
  • python libraries
  • Static served files
  • Media directories (i.e., public directories that the application can write to)


Let's assume, you develop a WSGI application that uses Flask and MySQL. In your project's root directory, put a file named config.json with this content:

    "application": "yourapp",
    "version": "6",
    "dependencies": [
    "features": {
        "mysql": true

In we put some application logic:

from MySQLdb import connect
from flask import Flask, g
from homunculus_instancetools import config

application = Flask(__name__)
application.config['PROPAGATE_EXCEPTIONS'] = True

def index():
    cursor = g.connection.cursor()
    cursor.execute('select name from widgets')
    names = [name for name, in cursor.fetchall()]
    return u"These are your widgets: %s" % ', '.join(names)

def connect_db():
    g.connection = connect(**config['mysql']['credentials'])

def setup_database():
    cursor = connect(**config['mysql']['credentials']).cursor()

    # check if setup is necessary
    cursor.execute("show tables like 'name'")
    if cursor.fetchall():

    # set up widget table
    cursor.execute("create table widgets (name varchar(50))")
    cursor.execute("insert into widgets (name) values ('Flux Compensator')")

Run your application locally by cd'ing into the applications directory, and running: --mysql=mysql://user:pass@host/dbname

Watch the output by opening http://localhost:8080 with your browser.

Project Structure

Homunculus is divided into subprojects


homunculus_cli provides the command line tools necessary for the development and packaging of web applications with homunculus. If you want to develop WSGI applications, this is what you need.

See for details


homunculus_server provides the server side interface to deploy and run python web applicationss. If you want to serve WSGI-applications, this is what you need.

See for details


homunculus_instancetools provides the interface for applications running inside homunculus to access their configuration. Homunculus servers install this package automatically, so you don't need to install it yourself.

See for details

Recent activity

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.