Embed Size (px)
Citation preview
homunculus server DocumentationRelease 1.2.2
keppla
May 27, 2014
Contents
1 Introduction 3
2 Installation 52.1 Prerequisite Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 MySQL database and user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3 Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.4 Setting up the Virtualenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.5 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.6 Finializing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Package Features 73.1 Mounting Static Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Requesting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4 Hacking 11
5 License 13
6 Indices and tables 15
Python Module Index 17
i
ii
homunculus server Documentation, Release 1.2.2
Contents:
Contents 1
homunculus server Documentation, Release 1.2.2
2 Contents
CHAPTER 1
Introduction
Homunculus-Server is a webservice, that automatically installs dependencies and provides infrastructure like databasesfor WSGI applications.
That goal is achieved by providing a web interface for managing installed WSGI applications and by automaticallyconfiguring webserver, databases.
3
homunculus server Documentation, Release 1.2.2
4 Chapter 1. Introduction
CHAPTER 2
Installation
In the following, we install Homunculus in a virtualenv, and configure it for usage with Apache, mod_wsgi andMySQL.
2.1 Prerequisite Software
First, make sure you have the following software installed:
• Apache2
• mod_wsgi
• python
• virtualenv
• mysql-server
On ubuntu, sudo apt-get install apache2 libapache2-mod-wsgi python-virtualenv mysql-server should suffice.
2.2 MySQL database and user
To create the database and user homunculus will use, enter the following in a mysql-shell:
CREATE DATABASE homunculus;GRANT ALL PRIVILEGES ON *.* TO ’homunculus’@’localhost’ WITH GRANT OPTION;FLUSH PRIVILEGES;
2.3 Privileges
Homunculus needs privileges to restart the webserver, via sudo /etc/init.d/apache2 reload. To grant these privileges,on ubuntu/debian edit your sudoers file, and append the following:
www-data ALL = NOPASSWD: /etc/init.d/apache2
5
homunculus server Documentation, Release 1.2.2
2.4 Setting up the Virtualenv
Choose a directory where you want to install homunculus. In this example, we assume /var/www/homunculus
$ mkdir -p /var/www/homunculus$ mkdir -p /var/www/homunculus/data$ mkdir -p /var/www/homunculus/data/webserver/apache$ cd /var/www/homunculus
To install the dependencies in a virtualenv run this:
$ virtualenv --no-site-packages pythonenv$ pythonenv/bin/pip install homunculus_server mysql-python
2.5 Configuration
Copy the file examples/runner.wsgi into /var/www/homunculus, and edit it, so that it fits your needs.
Add the following lines to your apache config:
Include /var/www/homunculus/data/webserver/apache
<VirtualHost *>ServerName homunculus.example.comWSGIScriptAlias / /var/www/homunculus/runner.wsgi
</VirtualHost>
2.6 Finializing
Make sure, all files beneath /var/www/homunculus are writeable by the webserver. Assuming the webserver’s user iswww-data, you can achieve that by this command:
sudo chown www-data:www-data -R /var/www/homunculus
Restart apache. The command is something like /etc/init.d/apache2 reload, reload apache2 or simimlar, and dependson your OS.
With a webbrowser, visit http://homunculus.example.com/migrations/ and click “Execute all”
Go to http://homunculus.example.com. Homunculus should now be running.
6 Chapter 2. Installation
CHAPTER 3
Package Features
3.1 Mounting Static Files
Packages can provide files for the webserver to serve. To serve files, add this lines to your config.json:
"static": {"relative/path/in/package": "public/web/path",# ...
}
3.2 Requesting Features
A Package can request features such as databases, caching services, etc. All these requests are done with the configu-ration features:
"features:" {"featurename": {
# feature configuration},# ...
}
Currently, these features are available:
3.2.1 Hosting a Python WSGI-Application
Packages can contain python wsgi-applications. To serve one, add this lines to your features:
"python": {"dependencies": [
"flask","python-mysql",# ...
],"wsgi": {
"my.controller.module": "/",# ...
}}
7
homunculus server Documentation, Release 1.2.2
The controller module given in python.wsgi must contain a variable application that is as WSGI-application.
The given dependencies must be PyPi-names for python libraries. They will be installed via the fine package managerPIP.
copyright
3. 2011 Philipp Benjamin Köppchen
license GPLv3, see LICENSE for more details.
3.2.2 SQLite Database
With
"features: {"sqlite": true# ...
}
a package can request a SQLite Database. The database will stay between revisions.
The following configuration will be provided:
{"sqlite_path": "/path/to/sqlite/file.db"
}
copyright
3. 2011 Philipp Benjamin Köppchen
license GPLv3, see LICENSE for more details.
3.2.3 MySQL Database
With
"features": {"mysql": true# ...
}
a package can request a MySQL Database. The database will be freshly created if none exists for this application, andstay between revisions.
The following configuration will be provided:
{"credentials": {
"host": "localhost","db": "hom_conceptor","user": "hom_conceptor"
},"dburl": "mysql://hom_conceptor@localhost/hom_conceptor"
}
copyright © 2011 Philipp Benjamin Köppchen
license GPLv3, see LICENSE for more details.
8 Chapter 3. Package Features
homunculus server Documentation, Release 1.2.2
3.2.4 Memcached
With
"features": {"memcached": true,# ...
}
the usage of Memcached can be requested. The application can then use a memcached daemon, described in theprovided configuration:
{"host": "hostname","post": 12345
}
copyright
3. 2011 Philipp Benjamin Köppchen
license GPLv3, see LICENSE for more details.
3.2.5 Media Directory
With
"features": {"mediadir": {
’public_path’: ’/some/public/path’}#...
}
an application can request a directory, writable by the application, that will be served by the webserver.
The directory will stay between revisions.
The following configuration will be provided:
{"path": "/local/path/of/the/mediadir","public_path": "/some/public_path/path"
}
copyright
3. 2011 Philipp Benjamin Köppchen
license GPLv3, see LICENSE for more details.
3.2. Requesting Features 9
homunculus server Documentation, Release 1.2.2
10 Chapter 3. Package Features
CHAPTER 4
Hacking
• Make sure you have python, virtualenv and sqlite3 installed. (on ubuntu: sudo apt-get installpython-virtualenv should suffice)
• run make test to check if the tests run on your machine
• run make serve to start the standalone server
• ?
• profit
11
homunculus server Documentation, Release 1.2.2
12 Chapter 4. Hacking
CHAPTER 5
License
Homunculus is avialable under the terms of the GPLv3, for details see LICENSE
13
homunculus server Documentation, Release 1.2.2
14 Chapter 5. License
CHAPTER 6
Indices and tables
• search
15
homunculus server Documentation, Release 1.2.2
16 Chapter 6. Indices and tables
Python Module Index
hhomunculus_server.handlers.mediadir, 9homunculus_server.handlers.memcached, 8homunculus_server.handlers.mysql, 8homunculus_server.handlers.sqlite, 8homunculus_server.handlers.wsgi, 7
17
