Katar provides a simple, elegant way to manage and provision a Vagrant box on your local machine! Vagrant boxes are completely disposable. If something goes wrong, you can destroy and re-create the box in seconds!

Note: Katar is inspired by PHP's Laravel Homestead but with broader scope and without PHP dependencies. If developing web applications or in PHP Laravel Homestead is highly recommended.

Katar runs on any Windows, Mac, or Linux system, and by default uses a Vagrant box with almost everything you need to develop most applications.

Installing VirtualBox & Vagrant

Before launching your Katar environment, you must install VirtualBox and Vagrant. Both of these software packages provide easy-to-use visual installers for all popular operating systems.

Note: If you are using Windows, you may need to enable hardware virtualization (VT-x). It can usually be enabled via your BIOS.

Installing Katar

Katar is a Ruby Gem, therefore, Ruby must be installed on your local machine. Once Ruby is installed simply run the following command to install Katar:

gem install katar

Once you have installed the Katar Gem, run the init command to create the Katar.yaml configuration file:

katar init

The Katar.yaml file will be placed in the ~/.katar directory. If you're using a Mac or Linux system, you may edit Katar.yaml file by running the katar edit command in your terminal:

katar edit

If you would like to do some extra provisioning you may add any commands you wish to the after.sh file within the ~/.katar directory and they will be run after the Katar machine is provisioned.

Setting Your Box

The box property of the Katar.yaml file is the Vagrant box that will be utilized by your Katar environment. If no box is provided then ubuntu\wily64 will be created.

Note: Mysql and Postgres scripts run if a database is provided within the Katar.yaml file. Those database engines must be installed on the specified box for Katar to initialize properly. Simply comment out the database section within the Katar.yaml and configure the database manually if needing to run without those engines.

By default the box property is set to acmitch/katar-box. Included with that box is the following software:

Included Software
  • Ubuntu 15.10
  • Docker 1.10
  • Git
  • Subversion
  • Java 8
  • Python 2.7.10
  • Ruby 2.2.3 (RVM)
  • R
  • MySQL
  • Sqlite3
  • Postgres
  • NodeJs(With PM2, Browserify, Bower, Grunt, and Gulp)
  • Redis
  • Memcached

Included Applications

  • Xfce4 Desktop
  • Sublime Text 3
  • Terminator
  • Emacs
  • Vim

Note: If wishing to contribute clone acmitch/katar-box on GitHub.

Configuring Shared Folders

The folders property of the Katar.yaml file lists all of the folders you wish to share with your Katar environment. As files within these folders are changed, they will be kept in sync between your local machine and the Katar environment. You may configure as many shared folders as necessary:

folders:
    - map: ~/Workspace
      to: /home/vagrant/Workspace

Set Your SSH Key

Next, you should edit the Katar.yaml file. In this file, you can configure the path to your public SSH key, as well as the folders you wish to be shared between your main machine and the Katar virtual machine.

Don't have an SSH key? On Mac and Linux, you can generally create an SSH key pair using the following command:

ssh-keygen -t rsa -C "you@katar"

On Windows, you may install Git and use the Git Bash shell included with Git to issue the command above. Alternatively, you may use PuTTY and PuTTYgen.

Once you have created a SSH key, specify the key's path in the authorize property of your Katar.yaml file.

Launch The Vagrant Box

Once you have edited the Katar.yaml to your liking, run the katar up command in your terminal.

Vagrant will boot the virtual machine, and configure your shared folders! To destroy the machine, you may use the katar destroy command. For a complete list of available Katar commands, run katar help.

Commands:
  katar destroy         # Destroy the Katar machine
  katar edit            # Edit the Katar.yaml file
  katar halt            # Halt the Katar machine
  katar help [COMMAND]  # D``escribe available commands or one specific command
  katar init            # Create a stub Katar.yaml file
  katar provision       # Re-provisions the Katar machine
  katar provision       # Update the Katar machine image
  katar resume          # Resume the suspended Katar machine
  katar ssh             # Login to the Katar machine via SSH
  katar status          # Get the status of the Katar machine
  katar suspend         # Suspend the Katar machine
  katar up              # Start the Katar machine
  katar version         # Show Katar version number

Connecting To Your Databases

A katar database is configured for both MySQL and Postgres out of the box. You can add as many databases as you'd like by typing the katar edit command and editing the databases section of the Katar.yaml file. The username and password for all databases is root / secret.

Ports

By default, the following ports are forwarded to your Katar environment:

SSH: 2222 → Forwards To 22
HTTP: 8000 → Forwards To 80
HTTPS: 44300 → Forwards To 443
MySQL: 33060 → Forwards To 3306
Postgres: 54320 → Forwards To 5432
Forwarding Additional Ports

If you wish, you may forward additional ports to the Vagrant box, as well as specify their protocol:

ports:
    - send: 93000
      to: 9300
    - send: 7777
      to: 777
      protocol: udp

Desktop Mode

By default, VirtualBox machines are started in headless mode, meaning there is no UI for the machines visible on the host machine. To utilize the UI set the desktop property to true in the Katar.yaml file. During the boot process VirtualBox will open prompting login. When the boot processes finishes, simply login using the credentials vagrant/vagrant. Once logged in start the GUI by typing into the prompt:

xfce4-desktop