manala/manalize

Lightweight binary providing vagrant stacks provisionned through manala ansible roles

v0.6.0 2017-11-09 15:49 UTC

README

Build Status

This project provides ready-to-use development environments for various projects (Symfony projects, custom apps, etc.).

At this moment, provided environments are based on Vagrant and provisioned through Manala ansible roles.
Some Docker based implementations are planned and should appear really soon.

Why?

Because we are too lazy for manually setting up local development environments for each project we have to work on. In short, we need to:

  • Be able to work on any new/existing project from any platform in minutes
  • Enable/disable support for language, package or any various utility as well
  • Keep a local environment consistent across projects (practices, tools)
  • Have a local environment as close as possible from the production one
  • Destroy/rebuild any environment as needed

What's inside?

Manalize is built on the shoulders of the following libs :

Prerequisites

Installation

Using the installer (recommended):

curl -LSs https://raw.githubusercontent.com/manala/manalize/master/installer.php | php

Using composer:

composer global require manala/manalize

Using git:

git clone git@github.com:manala/manalize
cd manalize
composer install
make build
mv manalize.phar /usr/local/bin/manalize
chmod a+x /usr/local/bin/manalize

Usage

Checking that your host meets our requirements

Before using manalize, you need to ensure that your host is ready. It can easily be achieved by running the following command:

manalize check:requirements

A list of requirements and recommendations will be shown, sort as you can install/update packages depending on your need and the current state of your host.

Setting up your environment

Given you have a web project that you clone for the first time and you need to run locally, simply execute the setup command:

manalize setup <my-awesome-app>

This command interactively configures the virtual machine for your project.
Some files will be added to your project:

  • A Vagrantfile
  • A Makefile including some useful tasks that you'll need to use throughout your project
  • An ansible/ directory containing all the configuration related to the VM provisioning
  • Eventually some files specific to the chosen environment

Once this step done, your environment is ready so you can provision your VM using the following command:

make setup

Working with your environment

Once the setup process is finished (it may take a few minutes), your environment is operational and your VM is running. To manage it and work with it, just use the vagrant command-line tool as usual:

vagrant up|halt|reload|ssh

Keeping your environment up-to-date

Given your project's environment is there and your VM works well, its configuration is sticked to what we provided at the moment you created it.
Since the manala ansible roles evolve (and the corresponding templates as well), you may want to be aware of the important changes made to in order to update your environment accordingly.

To do so, there are two commands to be aware of: self-update and diff.

self-update

manalize self-update

Running this command updates your manalize binary to the latest release, coming with the latest configuration templates. After that, you can safely use the diff command as shown below.

diff

The diff command allows you to get a patch representing the diff between your current project configuration and the one that your current version of the manalize binary would have provided.

Getting the diff:

manalize diff --env="<env>" <my-awesome-app>

Getting the diff for applying the patch immediately:

cd <my-awesome-app>
manalize diff --env="<env>" | git apply

Getting the diff for applying the patch later:

cd <my-awesome-app>
manalize diff --env="<env>" > manalize.patch
git apply manalize.patch

Note:

⚠️ Be careful when applying the patch, any custom change made to your environment configuration will be erased. To minimize risks, we recommend you to look at the patch before trying to apply it.

Updating an existing environment without immediatly altering its configuration

Sometimes, it can be useful to setup the environment without affecting the existing project files nor adding new ones, when migrating a project which already uses Vagrant and/or Ansible for instance.

The following command will only update the ansible/.manalize metadata file from what you will configure:

manalize setup --no-update ~/my-awesome-app

So you can then apply a patch provided by the diff command.

Contributing

Getting the source code

git clone git@github.com:manala/manalize <path-to-manalize>

Using the executable

cd <my-awesome-app>
<path-to-manalize>/bin/manalize

Running the test suite

cd <path-to-manalize>
make test

Troubleshooting

Before all, please ensure your host satisfies each of our requirements. Your issue(s) may result from unsupported or buggy versions of packages installed on your machine.

If it doesn't, please consider opening an issue on this repository. We use github issues for tracking bugs, feature requests and ensuring support.

License

This project is licensed under MIT.
For the whole copyright, see the LICENSE file distributed with this source code.

Author information

Manala (http://www.manala.io/)