home | help 
REGGAE(1)		     General Commands Manual		       REGGAE(1)

NAME
     reggae  --  REGister  Globaly Access Everywhere is a package which helps in
     common DevOps tasks

SYNOPSIS
     reggae <command>

DESCRIPTION
     Reggae is an open source package which relays on base FreeBSD  and/or  CBSD
     to provide lower level management for jails and virtual machines.

     If  you  have ever used Vagrant or Docker Compose, Reggae is best described
     as an alternative to those. It enables you  easy  development  inside  jail
     while  code  editing is done on the host. It makes transition from develop-
     ment to production easier by using provisioners. It makes host clean of all
     requirements of development and puts  them  inside  jail  which  is  easily
     stopped, started, provisioned, and destroyed.

     To initialize Reggae, first edit /usr/local/etc/reggae.conf and add:

	   PROJECTS_DIR=/home/me/repos

     It  will  set  directory to be shared with virtual machines, like directory
     containing your projects. If you don't need such a directory, you	can  set
     it to /var/empty.

	   PROJECTS_DIR=/var/empty

     If  you  want to run Reggae with base jails, no need to do any other edits,
     but if you'd like to use CBSD as the backend, you need to add

	   BACKEND=cbsd

     run the following as root:

	   reggae host-init
	   # service pflog restart
	   # service pf restart
	   reggae backend-init
	   reggae network-init

     PF is initialized only if /etc/pf.conf  doesn't  exist  already.  In  those
     cases PF services should be restarted.

     Through config file in /usr/local/etc/reggae.conf you can change values for
     anything  Reggae  is  using. Ater reggae network-init, you'll get jail con-
     taining DHCP and DNS. They are used to lease IPs to jails and  virtual  ma-
     chines  and  to  register all resources in DNS so that you can use FQDN in-
     stead of IP addresses. This jail IP is used in /etc/resolvconf.conf if host
     has dynamic IP on egress, so that changes of network parameters are  passed
     to  the  appropriate  jail.  Also,  host  will  use DNS jail IP in /etc/re-
     solv.conf. In short, it enables you to not remember jail IPs when you  have
     to use them, but use <jail name>.<domain> to reference them.

PROJECT
     A project consists of:

     *	 Makefile - configured for use with project

     One  project can contain many services, and that's going to be shown in the
     generated Makefile. The SERVICES variable in it will be commented but popu-
     lated with example services. All services when downloaded will be	in  ser-
     vices/<service>  directory.  You can use preexisting services if you define
     USE = <service>. For example, you can write the following:

	   REGGAE_PATH = /usr/local/share/reggae
	   USE = letsencrypt mysql wordpress nginx
	   .include <${REGGAE_PATH}/mk/project.mk>

     This project will set Wordpress in a jail.

     You can run make <target> on the project:
	   *   destroy
	   *   devel
	   *   fetch
	   *   init
	   *   login service=<service>
	   *   provision
	   *   setup
	   *   up

     Special note for the devel target: your repo must have  bin/devel.sh  which
     will  be  run  on	the  host. All project targets can be suffixed with ser-
     vice=<service> but in the above list only those which require a service are
     explicitely mentioned. If the service is passed as an argument, the  target
     will be executed only on that service/jail.

ANSIBLE
     A service with ansible provisioner consists of:

     *	 Makefile - configured for use with Ansible

     *	 playbook  -  containing  group_vars, inventory and roles directories as
	 placeholders for files generated on the fly, but can be used to config-
	 ure your playbook

     *	 requirements.yml - list of requirements, with only one  initially.  All
	 requirements  from  this  file  are downloaded from Ansible Galaxy tem-
	 plates/site.yml.tpl - this file should be edited to  add/remove  roles,
	 playbooks, etc.

     When  ran	with this configuration, reggae will first check if ansible exe-
     cutable is available on  the host, and if it isn't, it will run pkg install
     ansible.  If you use Python's virtual environments, for  example,	you  can
     avoid having ansible available to everyone on the system.

CHEF
     A service with chef provisioner consists of:

     *	 Makefile - configured for use with chef

     *	 playbook - containing cookbooks/core/recipes/default.rb dummy script

     When  ran	with  this  configuration,  reggae will first check if chef exe-
     cutable is available, and if it isn't, it will run pkg install -y chef  in-
     side jail. Then it will mount playbook directory on /root/chef inside jail.
     To do actual provisioning, Reggae uses chef-client --local-mode.

PUPPET
     A service with puppet provisioner consists of:

     *	 Makefile - configured for use with puppet

     *	 playbook - containing cookbooks/core/recipes/default.rb dummy script

     When  ran	with  this configuration, reggae will first check if puppet exe-
     cutable is available inside jail, and if it isn't, it will install it  from
     packages.	 Then  it  will  mount playbook directory on /usr/local/etc/pup-
     pet/manifests inside jail. To do actual provisioning,  Reggae  uses  puppet
     apply.

SALT STACK
     A service with salt provisioner consists of:

     *	 Makefile - configured for use with salt

     *	 playbook - containing top.sls and core.sls playbooks

     When  ran	with  this  configuration,  reggae will first check if salt exe-
     cutable is available, and if it isn't, it will run pkg install -y py36-salt
     inside  jail.  Then  it  will  mount   playbook   directory   on	/usr/lo-
     cal/etc/salt/states  inside  jail.  To  do actual provisioning, Reggae uses
     salt-call --local state.apply.

SHELL
     A service with shell provisioner consists of:

     *	 Makefile - configured for use with shell

     *	 playbook - containing dummy provision.sh to start with

     When ran with this configuration, reggae will first mount	playbook  direc-
     tory on /root/shell inside jail. To do actual provisioning, Reggae will run
     /root/shell/provision.sh.

EXAMPLES
     Quickest way to get basic project is:

	   mkdir myproject
	   cd myproject
	   reggae init-project

     Quickest way to get basic service provisioned with Ansible is:

	   mkdir myservice
	   cd myservice
	   reggae init shell
	   make

     You  can have multiple provisioners, and the order they are declared on the
     command line is the order they will be executed in.

	   mkdir myservice
	   cd myservice
	   reggae init shell ansible
	   make

SEE ALSO
     jail(8) bhyve(8)

BUGS
     Report bugs to https://github.com/cbsd/reggae/issues.

AUTHORS
     Goran MekiA <meka@tilda.center>

FreeBSD ports 15.quarterly	  May 20, 2018			       REGGAE(1)
home | help