Installation¶
Installing the server¶
The Coalition server can be installed on a localhost or on a remote host. Please remember that communication between server and workers is not encrypted, so if the server is installed on localhost and workers on remote machines, using a VPN or a VLAN is a good idea.
Coalition works with python2.7.
Debian like, Ubuntu, etc. via system packages¶
Logged as a priviledged user, in a shell prompt, run:
apt-get install -y \
python2.7 \
python-httplib2 \
python-configparser \
python-twisted \
python-mysqldb \
python-ldap \
python-sphinx \
python-sphinxcontrib-httpdomain
cd /usr/local/bin
git clone https://github.com/MercenariesEngineering/coalition.git
cd coalition
cp _coalition.ini coalition.ini
Edit the section [server] in the file coalition.ini according to your needs.
You may want to fine tune the installation using:
- a dedicated system user and group to isolate the process and file ownership;
- a systemd service definition file;
- any system service monitoring daemon.
Via pip, the python package manager¶
Using a python virtual environment is advised in this case, although not mandatory.
Logged as a priviledged user, in a shell prompt, run:
cd /usr/local/bin
git clone https://github.com/MercenariesEngineering/coalition.git
cd coalition
pip install -r requirements.txt
cp _coalition.ini coalition.ini
Edit the section [server] in the file coalition.ini according to your needs.
You may want to fine tune the installation using:
- a dedicated system user and group to isolate the process and file ownership;
- a systemd service definition file;
- any system service monitoring daemon.
coalition.ini configuration file¶
This configuration file contains two sections: [server] that will be used in server mode, and [worker] that will be used while running in worker mode.
[server]
# Server configuration
# Type of database to use. "sqlite" for a file based database, "mysql" for an external mysql server.
#db_type=sqlite
# The sqlite database file
#db_sqlite_file=coalition.db
# The mysql server
#db_mysql_host=127.0.0.1
#db_mysql_user=
#db_mysql_password=
#db_mysql_base=base
#db_mysql_install=1
# Server port (default is 19211)
#port=19211
# Server mode [normal|aws|gcloud] (default is normal)
# If cloud mode is selected (all but "normal"), the corresponding
# configuration file has to be edited.
# eg. the file "aws_cloud.ini" for servermode="aws".
servermode=normal
# Worker time out in seconds, time lapse after a worker missing heartbeats is considered out (default is 10)
#timeout=10
# Run the server as service (Windows only)
#service=0
# Display verbose logs
#verbose=0
# Notify the user after the N first children jobs have been finished. 0 disables this notification.
#notifyafter=10
# Decrease the priority of a parent job after N errors.
#decreasepriorityafter=10
# SMTP server hostname, emails disabled if empty
#smtphost=
# SMTP server port
#smtpport=587
# SMTP use a TLS connection
#smtptls=1
# SMTP sender email
#smtpsender=
# SMTP server login, no authentification if empty
#smtplogin=
# SMTP server password, no authentification if empty
#smtppasswd=
### LDAP configuration ###
# LDAP server to use for authentication
# If not empty, coalition will require a login and a password at every requests
; ldaphost=ldap://localhost
# Set to True to prevent password validation for API requests.
# Useful for scripts using API as it prevents hard-writing passwords.
# Authentification is still required while serving index.html to force web frontend users login.
; ldapunsafeapi=True
# LDAP base (used for searches)
; ldapbase=dc=ldap,dc=localhost,dc=lan
# LDAP template used to validate the user, eg.
# uid=cn=__login__,ou=people,dc=example,dc=com
# where __login__ will be replaced by the user login
; ldaptemplatelogin = cn=__login__,dc=ldap,dc=localhost,dc=lan
### Group permissions ###
# Permissions are defined following the generic CRUD actions.
# Two major modes are predefined: per user or global.
# Per user mode offers CRUD actions only for jobs owned by the user.
# Global mode offers CRUD actions to the user for any job.
#
# Per user actions:
# createjob: User can create jobs owned by himself.
# viewjob: User can see his jobs.
# editjob: User can edit his jobs.
# deletejob: User can delete his jobs.
#
# Global actions:
# createjobglobal: User can create a job owned by any other user.
# viewjobglobal: User can see any job.
# editjobglobal: User can edit any job.
# deletejobglobal: User can delete any job.
#
# LDAP template are used to validate that the user belongs to a specific group
#
# For instance, 3 permission groups can be defined in LDAP this way:
# 1. administrators: Can create, view, edit and delete any job.
# 2. wranglers: Can create, view and edit any job (but not delete).
# 3. artists: Can create, view, edit and delete only his own jobs.
#
# __login__ is replaced by the username.
; ldaptemplatecreatejob=(& (cn=artists) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplateviewjob= (& (cn=artists) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplateeditjob= (& (cn=artists) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplatedeletejob=(& (cn=artists) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplatecreatejobglobal=(& (| (cn=administrators) (cn=wranglers) ) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplateviewjobglobal= (& (| (cn=administrators) (cn=wranglers) ) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplateeditjobglobal= (& (| (cn=administrators) (cn=wranglers) ) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
; ldaptemplatedeletejobglobal=(& (cn=administrators) (member=cn=__login__,dc=ldap,dc=localhost,dc=lan) )
# Command white list.
# For global permission, use "global" as first parameter
# For per user permission, use "<username>" as first paramater
# Global and per user command while list.
#commandwhitelist=global command1 regexp
# global command2 regexp
# @user1
# user1 command1 regexp The command white list can be global or per user.
# user1 command2 regexp
# @user2
# user2 command1 regexp
# user2 command2 regexp
[worker]
# Worker configuration
# Server URL, like http://serverhost:19211, let it blank to use autodetection by broadcasting.
#serverUrl=
# Number of simultaneous workers on this system (default is 1)
#workers=1
# Worker name (default is host name)
#name=MyWorker
# Sleep time between two heartbeats in seconds (default is 2)
#sleep=2
# Maximum number of cpus per worker, will override the number of workers when defined (Windows only)
#cpus=None
# Command to execute at worker startup
#startup=
# Display verbose logs
#verbose=0
# Customize the command used to run the job.
#
# The command set in runcommand is responsible for :
# * changing the user
# * changing the working directory
# * run the job command with the current environment
#
# The following pattern will be replaced:
# __user__ : the job user name
# __dir__ : the job directory
# __cmd__ : the job command
#
# If runcommand is blank, the worker set the working directory to the job directory
# and run the command using the worker permissions.
# Default run command
#runcommand=
# Run the jobs using sudo
#runcommand=sudo -u __user__ -E -- sh -c 'cd __dir__; __cmd__'
# Workers log file
#logfile=./worker.log
Cloud mode¶
A coalition server must be installed and the cloud provider needs configuration. See cloud mode documentation page for details.
Database¶
A database must be setup for the coalition server. To initialize it the firest time, run:
python server.py --verbose --init
The database can be reset on demand. All data are lost:
python server.py --verbose --reset
See also the next section about migrations.
Update coalition to a new release¶
If you update the coalition source code with a more recent coalition release, the new coalition features may need a database schema update. If it’s the case, you will be informed by a message while trying to run the server:
python server.py --verbose --init
# ...
# The database requires migration
In this case, you should use the –migrate option to explicitely reconfigure the database:
python server.py --verbose --init
# ...
# Migration was sucessful
Running the server¶
When all has been set up, run:
python server.py
To see available command line arguments, run:
python server.py --help
On windows, use one those options:
python server.py --console
python server.py --service
Installing a worker¶
The same procedure than above in installing a server applies, except for configuration and running.
Configuration¶
Edit the section [worker] of the configuration file coalition.ini according to your needs.
You may want to fine tune the installation using:
- a dedicated system user and group to isolate the process and file ownership;
- a systemd service definition file;
- any system service monitoring daemon.