Running multiple instances¶
You might want to run multiple instances of RestAuth on the same host. This
would mean that you effectively have two RestAuth servers (e.g.
auth.example.com
and auth.example.org
), each with their own
users, groups and services. You could maintain two completely separate
installations (maybe even on separate hosts), but that would require twice the
maintenance. This page is dedicated to documenting (known) configuration tips
regarding this problem.
General introduction¶
The only thing that really needs to differ from instance to instance is the database.
If two instances access the same database, they effectively become the same instance with possibly different configuration. You could imagine exotic different scenarios, like one instance requiring a minimum password length of 10 characters and another instance requiring a minimum password length of 12 characters, but they makes little sense. If you desire such a setup, you can still use any of the following chapters, but examples are based on the assumption that you want a different database setup.
Server Name Indication¶
All examples below use Server Name Indication (SNI). That means that the web server (in the configuration examples, Apache) is able to serve multiple domains on the same IP via SSL. If you want to use SNI, both client and server need to support it.
On most modern systems, server side
support is not a problem. See the
appropriate chapter on WikiPedia for
more information on the required software versions. On the client side, the
situation is a little more tricky. RestAuthClient only supports SNI if run with Python 3.2 or
later. php-restauth supports SNI if compiled with
OpenSSL/GNU TLS and libcurl versions that support it.
If using SNI is not an option, the web server can serve different instances on different ports and/or different IP addresses.
Settings based on environment variables¶
Since RestAuth/localsettings.py
is just a normal Python file, you can use any Python
code you want in it. The best way of getting multiple instances with the least
configuration overhead is by using
environment variables.
First, you must make sure that some environment variable is different for each RestAuth instance you want to maintain. You can set this anywhere you like, please consult the appropriate documentation for your web server. The following example sets environment variables in a mod_wsgi deployment.
Note
This Apache configuration example uses Server Name Indication. See the dedicated chapter for more information.
Note
Many server setups, including WSGI applications, do not pass environment variables set in the apache configuration to the python interpreter. Please consult your webserver documentation if you have trouble retrieving the right environment variables.
The WSGI script that ships with RestAuth specifically
passes RESTAUTH_HOST
and DJANGO_SETTINGS_MODULE
if present.
Other environment variables are filtered, if you need additional environment
variables, you need to modify the WSGI script.
<VirtualHost *:443>
ServerName auth.example.com
# ...
# if you want to run WSGI processes as their own user:
WSGIProcessGroup restauth-com
WSGIDaemonProcess restauth-com user=restauth group=restauth processes=1 threads=10
SetEnv RESTAUTH_HOST auth.example.com
</VirtualHost>
<VirtualHost *:443>
ServerName auth.example.org
# ...
# if you want to run WSGI processes as their own user:
WSGIProcessGroup restauth-org
WSGIDaemonProcess restauth-org user=restauth group=restauth processes=1 threads=10
SetEnv RESTAUTH_HOST auth.example.org
</VirtualHost>
You can now use RESTAUTH_HOST
in RestAuth/localsettings.py
to determine
settings based on the host that the client accesses. To configure different
databases, the file might look like this:
# ...
import os
# get environment variable, .com is the default if undefined
RESTAUTH_HOST = os.environ.get( 'RESTAUTH_HOST', 'auth.example.com' )
if RESTAUTH_HOST == 'auth.example.com':
DATABASES = {
'default': {
DATABASE_ENGINE = 'postgresql_psycopg2',
DATABASE_NAME = 'restauth',
DATABASE_USER = 'restauth',
DATABASE_PASSWORD = 'POSTGRES_PASSWORD', # you really should change this!
DATABASE_HOST = '',
DATABASE_PORT = '',
}
}
else: # auth.example.org is the default
DATABASES = {
'default': {
'ENGINE': 'mysql',
'NAME': 'restauth',
'USER': 'restauth',
'PASSWORD': 'MYSQL_PASSWORD', # you really should change this!
'HOST': '',
'PORT': '',
}
}
In this example, auth.example.org
uses a PostgreSQL database and
auth.example.com
uses a MySQL database. You can use this setup to set
any other setting based on the hostname.
Separate settings files¶
Another, slightly more maintenance intensive way, is to use different
settings.py
files altogether. All settings are duplicated in this
configuration, if you want to share common configuration, you can still have
them in the file RestAuth/localsettings.py
as described in the examples below.
The Apache configuration is similar, only that you use the standard Django
environment variable DJANGO_SETTINGS_MODULE
:
Note
This Apache configuration example uses Server Name Indication. See the dedicated chapter for more information.
Note
Many server setups, including WSGI applications, do not pass environment variables set in the apache configuration to the python interpreter. Please consult your webserver documentation if you have trouble retrieving the right environment variables.
The WSGI script that ships with RestAuth specifically
passes RESTAUTH_HOST
and DJANGO_SETTINGS_MODULE
if
present. Other environment variables are filtered, if you need additional
environment variables, you need to modify the WSGI script.
<VirtualHost *:443>
ServerName auth.example.com
# ...
SetEnv DJANGO_SETTINGS_MODULE RestAuth.settings_com
</VirtualHost>
<VirtualHost *:443>
ServerName auth.example.org
# ...
SetEnv DJANGO_SETTINGS_MODULE RestAuth.settings_org
</VirtualHost>
You then create two new files, settings_com.py
and
settings_org.py
in the same location as settings.py
. Each file
might look like this:
# First, include settings from settings.py, as it includes useful defaults. If this fails, it
# generally means that this file is in the wrong location.
from settings import *
# now for some settings individual to this installation
DATABASES = {
'default': {
DATABASE_ENGINE = 'postgresql_psycopg2',
DATABASE_NAME = 'restauth',
DATABASE_USER = 'restauth',
DATABASE_PASSWORD = 'POSTGRES_PASSWORD', # you really should change this!
DATABASE_HOST = '',
DATABASE_PORT = '',
}
}
You can now configure each instance separately. The file RestAuth/localsettings.py
is still included in settings.py
, so you can use it to share settings
for every instance.
Access different hosts via command line¶
To access the different RestAuth instances via our command-line tools (restauth-service.py, restauth-user.py, restauth-group.py and restauth-import.py), you simply have to set the correct environment variables on the command line first:
user@host ~ $ restauth-service.py ls # will access auth.example.org user@host ~ $ export RESTAUTH_HOST=auth.example.com user@host ~ $ restauth-service.py ls # will access auth.example.com
... of course, you can still configure this on a per-command basis:
user@host ~ $ RESTAUTH_HOST=auth.example.com restauth-service.py ls