README

Dependencies :
==============

	lodel2 components :
	-------------------
		core :
			python3 python3-lxml

		build dependencies :
			autoconf automake make

		webui plugin :
			python3-jinja2 python3-werkzeug uwsgi-plugin-python3

		mongodb_datasource plugin :
			python3-pymongo

	lodel2 utils :
	--------------
		mass_deploy dependencies :
			pwgen wamerican mongodb-clients

Build & install :
=================

	./bootstrap.sh #generate the configure, refresh the Makefile.in files
	#--prefix=/usr is mandatory on debian because of a python3.4.2 bug
	./configure --sysconfdir=/etc --localstatedir=/var --prefix=/usr
	#build lodel2 (actually substitute paths script and buildconf.py files)
	make
	#Install lodel2 on system
	make install
	#Uninstall lodel2
	make uninstall

Creating debian package :
=========================

	make deb

Other make targets :
====================

	Doxygen documentation generation :
	----------------------------------
		make doxygen

	Run unit tests :
	----------------

		make check
		#or
		make unittest
	
	Cleaning to stop being annoyed when running git status :
	--------------------------------------------------------
		
		make gitclean

Lodel2 instance management utilities :
======================================
NOTE: You have to run in root to use this below
	SLIM : Simple Lodel Instance Manager
	------------------------------------

		- create a new instance named foo :
			slim -n foo -c

		- list instances : 
			slim -l

		- list instances with details :
			slim -lv[v[v]]

		- list instances with output formated for bash processing :
			slim -l -b [-v[v[v]]

		- run make all for instance foo :
			slim -n foo -m

		- run make for all existing instances :
			slim --all -m

		- start an instance in forground
			slim -n foo --start -f

		- start all instances :
			slim -a --start

		- generate a nginx conf for all instances :
			slim -a --nginx-conf

		- set logger to warning level and log in file :
			slim -a -s --set-logger test:WARNING:/var/log/lodel2/%l.%s.log

		- get some help for more options & actions :
			slim -h


	mass_deploy.sh :
	----------------
		Use for easy mass deployment of instances with webui & uwsgi
		the script at $prefix/share/lodel2/scripts/mass_deploy.sh

		Usage : 
		-------
			#with N the number of instances to deploy
			mass_deploy.sh N 		

		Notes :
		-------

		- configuration can be found in /etc/lodel2/mass_deploy.cfg 
		  to indicate mongodb admin credentials

		- mass deploy create instances directories 
		  in /tmp/lodel2_instances

Mass deployments tricks & tips:
===============================

	Mass deployment on fresh install :
	----------------------------------
	
	#Install nginx & mongodb
	apt-get install nginx mongodb-server mongodb-clients
	#choose your credential
	export mongoadmin="admin"; export mongopass="pass";
	#Disable auth to be able to connect to mongodb
	sed -ie 's/^#noauth = /noauth = /' /etc/mongodb.conf
	#Add an admin user to mongodb
	echo -e "use admin\ndb.addUser('$mongoadmin', '$mongopass')\nexit\n"|mongo
	#Reactivate auth
	sed -i -e 's/^noauth = /#noauth =/' -e 's/^#auth = /auth =/' /etc/mongodb.conf
	#Test connection
	echo "exit" | mongo --quiet -u $mongoadmin -p $mongopass admin && echo "Connection ok" || echo "connection fails"
	#Indicate mongodb credentials to mass_deploy
	echo -e "MONGODB_ADMIN_USER='$mongoadmin'\nMONGODB_ADMIN_PASSWORD='$mongopass'\n" >> /etc/lodel2/mass_deploy.cfg
	#Deploying 50 instances
	NINSTANCE=50
	#Running mass_deploy
	/usr/share/lodel2/scripts/mass_deploy $NINSTANCE

	#FOLLOWING INSTRUCTIONS ARE FOR STARTING APPS WITH UWSGI
	# for standalone instructions see bellow

	#Updating nginx conf (delete /etc/nginx/sites-enabled/default if exists)
	slim --nginx-conf -a > /etc/nginx/sites-enabled/lodel2
	/etc/init.d/nginx reload
	#Start all instances and check if they managed to start
	slim --start -a && sleep 2 && slim -l

	# FOLLOWING INSTRUCTIONS ARE FOR STANDALONE LODEL2 WEBSERVER
	
	#Configure nginx & restart it
	export lodel2_install_dir="/usr/lib/python3/dist-packages";
	echo -e "server {\n\tlisten 80 default_server;\n\tlisten [::]:80 default_server;\n\tlocation / {\n\t\tproxy_pass http://localhost:1337/;\n\t}\n\t\n\tlocation /static/ {\n\t\talias $lodel2_install_dir/lodel/plugins/webui/templates/;\n\t}\n\t\n}\n" > /etc/nginx/sites-enabled/default
	/etc/init.d/nginx restart
	#Build dyncode for instances
	slim -a -m
	#Copy the multisite loader in lodel instances root folder
	cp /usr/lib/python3/dist-packages/lodel/plugins/multisite/loader.py /tmp/lodel2_instances/
	cd /tmp/lodel2_instances/
	#Start the server
	python3 loader.py
	#Now you can access to the app in HTTP via nginx throught port 80 
	#or directly via the python server throught the port 1337


	Cleaning mongodb + instances :
	------------------------------

	slim --purge && /usr/share/lodel2/scripts/mass_deploy purgedb ; slim -l

	Debuging an instance in foreground (if it didn't manage to start) :
	-------------------------------------------------------------------

	slim --start -f -n INSTANCE_NAME

Instance operations :
=====================

	- Two utils are available for instances operations :
		* Make for op without parameters
		* lodel_admin.py for op with parameters

	- Makefile available target :
		# Leapi dynamic code creation ( in leapi_dyncode.py in lodel2 
		#instance root dir)
		make dyncode 

		# Call migration handlers to tell them to init all needed 
		#databases. (note : this target has dyncode as dependencie)
		make init_db 
		make list_hooks # List all the hooks registered

	- lodel_admin.py : see lodel_admin.py -h


##########################################
# Following informations can be obsolete #
##########################################

Dynamic code generation :
	python3 scripts/refreshdyn.py examples/em_test.pickle OUTPUTFILE.py

Instance creation :
	Use the script in scripts/create_instance.sh

	Usage : scripts/create_instance.sh instance_name instance_dir [lodel_libdir]


Instance loader uppdate :
	If the install/loader.py is updated you can update instance's loader.py using
		scripts/create_instance.sh -u INSTANCE_PATH