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, Docker containers and without PHP dependencies.

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.

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

Included Software

  • Ubuntu 15.10
  • Git
  • Docker
  • Java 8
  • Sqlite3
  • Memcached
  • Subversion
  • Python 2.7.10
  • Ruby 2.2.3 (RVM)
  • NodeJs(With PM2, Browserify, Bower, Babel, Webpack, and Gulp)
  • R

Docker Containers

  • MySQL
  • Postgres
  • MongoDB
  • Redis
  • Elasticsearch

Included Applications

  • Xfce4 Desktop
  • Sublime Text 3
  • Terminator
  • Emacs

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

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:

# Start the VM desktop
xfce4-desktop

# Turn on bidirectional clipboard
clipboard-on

Docker Containers

Docker containers are used to support multiple services within Katar by default.

# Display all containers
docker ps -a

# Start a Docker MongoDB container
docker start mongo-db