Embedding an application in uWSGI¶
Starting from uWSGI 0.9.8.2, you can embed files in the server binary. These can be any file type, including configuration files. You can embed directories too, so by hooking the Python module loader you can transparently import packages, too. In this example we’ll be embedding a full Flask project.
Step 1: creating the build profile¶
We’re assuming you have your uWSGI source at the ready.
In the buildconf
directory, define your profile – let’s call it flask.ini:
[uwsgi]
inherit = base
main_plugin = python
bin_name = myapp
embed_files = bootstrap.py,myapp.py
myapp.py
is a simple flask app.
from flask import Flask
app = Flask(__name__)
app.debug = True
@app.route('/')
def index():
return "Hello World"
bootstrap.py
is included in the source distribution. It will extend the python import subsystem to use files embedded in uWSGI.
Now compile your app-inclusive server. Files will be embedded as symbols in the executable. Dots and dashes, etc. in filenames are thus transformed to underscores.
python uwsgiconfig.py --build flask
As bin_name
was myapp
, you can now run
./myapp --socket :3031 --import sym://bootstrap_py --module myapp:app
The sym://
pseudoprotocol enables uWSGI to access the binary’s embedded
symbols and data, in this case importing bootstrap.py directly from the binary
image.
Step 2: embedding the config file¶
We want our binary to automatically load our Flask app without having to pass a long command line.
Let’s create the configuration – flaskconfig.ini:
[uwsgi]
socket = 127.0.0.1:3031
import = sym://bootstrap_py
module = myapp:app
And add it to the build profile as a config file.
[uwsgi]
inherit = base
main_plugin = python
bin_name = myapp
embed_files = bootstrap.py,myapp.py
embed_config = flaskconfig.ini
Then, after you rebuild the server
python uwsgiconfig.py --build flask
you can now simply launch
./myapp
# Remember that this new binary continues to be able to take parameters and config files:
./myapp --master --processes 4
Step 3: embedding flask itself¶
Now, we are ready to kick asses with uWSGI ninja awesomeness. We want a single binary embedding all of the Flask modules, including Werkzeug and Jinja2, Flask’s dependencies. We need to have these packages’ directories and then specify them in the build profile.
[uwsgi]
inherit = default
bin_name = myapp
embed_files = bootstrap.py,myapp.py,werkzeug=site-packages/werkzeug,jinja2=site-packages/jinja2,flask=site-packages/flask
embed_config = flaskconfig.ini
Note
This time we have used the form “name=directory” to force symbols to
a specific names to avoid ending up with a clusterfuck like
site_packages_flask___init___py
.
Rebuild and re-run. We’re adding –no-site when running to show you that the embedded modules are being loaded.
python uwsgiconfig.py --build flask
./myapp --no-site --master --processes 4
Step 4: adding templates¶
Still not satisfied? WELL YOU SHOULDN’T BE.
[uwsgi]
inherit = default
bin_name = myapp
embed_files = bootstrap.py,myapp.py,werkzeug=site-packages/werkzeug,jinja2=site-packages/jinja2,flask=site-packages/flask,templates
embed_config = flaskconfig.ini
Templates will be added to the binary… but we’ll need to instruct Flask on how to load templates from the binary image by creating a custom Jinja2 template loader.
from flask import Flask, render_template
from flask.templating import DispatchingJinjaLoader
class SymTemplateLoader(DispatchingJinjaLoader):
def symbolize(self, name):
return name.replace('.','_').replace('/', '_').replace('-','_')
def get_source(self, environment, template):
try:
import uwsgi
source = uwsgi.embedded_data("templates_%s" % self.symbolize(template))
return source, None, lambda: True
except:
pass
return super(SymTemplateLoader, self).get_source(environment, template)
app = Flask(__name__)
app.debug = True
app.jinja_env.loader = SymTemplateLoader(app)
@app.route('/')
def index():
return render_template('hello.html')
@app.route('/foo')
def foo():
return render_template('bar/foo.html')
POW! BIFF! NINJA AWESOMENESS.