Project Setup and Maintenance

Project Setup and Maintenance

You already have Vain ready for development? Start contributing! Get a feeling for the platform by reading the Deep Dive Development guide.

Table of Contents

1. Introduction
2. Environment
3. Dependencies
   • Backend
   • Frontend
4. Database
   • Migration
   • Seeding
5. Asset Management
6. Testing
7. You did it!
   • Where to go from here?

Introduction

These steps are generally required multiple times. You will need to follow them in sequential order if you boot your Homestead VM for the first time. Later on you may need some of them for maintaining the development environment and to complement your development work.

NOTE: All of the following steps are performed through an SSH connection to your Homestead VM. To open a SSH connection fire up your terminal and type homestead ssh.

Environment

You have to supply some environment specific variables to run the application. Having its roots in the ruby community the DotEnv concept is used. For your local development environment just copy the .env.example stub file to .env (don't commit that to any repository!). Check the key-value pairs and verify that everything is correct.

For more information about DotEnv visit the Laravel Documentation.

Dependencies

All dependency management tools have to run from the project root. We use the following dependency management tools for both backend and frontend:

• Composer / Repository for Backend
• NPM for Frontend
• Bower / Repository for Frontend

NOTE: All of them are shipped with Homestead out of the box.

Backend

Install all PHP backend dependencies with the command composer install or composer updaterespectively. It reads its dependencies out of the composer.json file.

Examples: laravel, phpSpec, entrust

Please don't .gitignore the composer.lock file. Commit it to the repository. It is necessary to install correct dependency versions in production. (Source)

For more Information about Composer visit the Composer Documentation.

Frontend

Why using two dependency managers for the frontend? NPM is commonly used for installing server or backend dependencies along with Node, while Bower is used for the client-side dependencies. You can not really differentiate the two dependency managers general nowadays, but for the Vain project you can think of them like the following.

NPM the Node Package Manger

..is used to install all system level requirements. Those are necessary to build the frontend but are not required to actually run it. You can think of them as compile-time dependencies. Install those by running the command npm install in your terminal. It reads its dependencies out of the package.json file.

Examples: grunt, less

For more Information about NPM visit the NPM Documentation.

Bower

..is used to install all frontend frameworks upon which the UI and UIX is built. You can think of them as runtime dependencies. Install those - like you would do with composer - using the bower install or bower update command respectively. It reads its dependencies out of the bower.json file.

Examples: bootstrap, AdminLTE

For more Information about Bower visit the Bower Documentation.

Database

Since we use a module architecture in Vain there are some differences to how you normally would migrate and seed a database in Laravel.

NOTE: The default artisan database commands will also work but they do not affect the modules.

For more Information about arisan commands for modules visit the Module Artisan Commands page.

Migration

Create new migration for the specified module.

• php artisan module:migration MIGRATION MODULE

Rollback, Reset and Refresh The Modules Migrations.

• php artisan module:migrate-rollback
• php artisan module:migrate-reset
• php artisan module:migrate-refresh

Rollback, Reset and Refresh The Migrations for the specified module.

• php artisan module:migrate-rollback MODULE
• php artisan module:migrate-reset MODULE
• php artisan module:migrate-refresh MODULE

NOTE: See this pitfall with module:migrate-rollback.

Migrate from the specified module.

• php artisan module:migrate MODULE

Migrate from all modules.

• php artisan module:migrate

Seeding

Seed the mandatory dependencies (default permissions and roles) with the following command:

• php artisan db:seed

Create new seed for the specified module.

• php artisan module:seed-make SEED MODULE

Seed from the specified module.

• php artisan module:seed MODULE

Seed from all modules.

• php artisan module:seed

Asset Management

Building the Frontend is super easy. Since Elixir is built on top of gulp, you only have to run gulp. If you are actively developing the frontend you may choose gulp watch as it automatically triggers recompiles if you change an asset file.

To get an in-depth guide how to handle assets read the How to Elixir guide.

Testing

To get more information about testing read the Testing Techniques guide.

You did it!

Very well, you are ready for development. If you need assistance for some maintenance processes you can come back and use this page as an cheatsheet anytime you want.

Where to go from here?

Start contributing! Get a feeling for the platform by reading the Deep Dive Development guide.