Skip to content

takeoff-env/takeoff

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Takeoff Rapid Development Toolkit

Takeoff is a toolkit for rapid development, allowing you to prototype web applications using it's command line tool.

Installed via npm you can find a list of commands via takeoff help for creating and managing Takeoff environments and projects. Projects are created based on Blueprints.

Install Takeoff

Installing takeoff is simple, via NPM.

npm install -g @takeoff/takeoff
takeoff init <myenv> # Creates an environment for your projects, if not passed will create a folder called "takeoff"
cd <myenv>
takeoff start # This starts the project in `projects/default`

This creates an initial "Environment" - folders containing blueprints, projects and commands, alongside a .takeoffrc file. Blueprints are the heart of Takeoff and allow a way to easily distribute projects for Proof of Concepts, Hackdays, Code Camps and many more uses. A blueprint is used to create projects, essentially a working environment that contains the project sources and docker file. Commands are custom scripts you can add you any blueprint that are shipable.

It starts with a blueprint

Blueprints are repositories with some batteries included applications and configurations for containers. Takeoff uses these to build a full working environment in minutes. A blueprint generally contains a backend component, a frontend, a database and an ingress server.

Currently Takeoff only ships with the default blueprint (but it's relativly easy to create new ones!) called takeoff-blueprint-basic and it provides:

Configuring the Blueprint

Configuring the setup of the blueprint application is done via a very easy takeoff.md file included in the root directory.

You can find an example file here with details on how it works.

Default Blueprint

The default blueprint for API comes batteries included:

  • A node API server powered by Hapi and written in TypeScript. Included in the application is a User system for username/password login and basic user management, 2 levels (admin and user - and easily extendible). There is also a JSON Web Token (JWT) authentication system that gives you control over access to your API endpoints.

  • An Angular Frontend with Bootstrap 4. The frontend comes with a basic Dashboard layout and homepage. A login page with some basic validation allows you to log in (the default login is admin/password). There are some additional components in development, but this is enough to get started on a basic app.

Do not expect this to be a fully secure environment. Once logged in you have a basic user CRUD application to manage users, and a navigation bar that you can customise. Disclaimer: If you build an app with this you wish to deploy, you are responsible for your own security.

  • A MongoDB database using Mongoose to make model development easy. There is a basic user table and seeded admin user provided. It's easy to add your own models, or update pre-existing ones.

  • A Nginx ingress server, by default running on port 80 (which means you get http://localhost or http:// as your address. If you cannot run on port 80, it can be configured in the docker-compose.yml by changing the first number of the pair (e.g "8080:80")

Under the hood it uses docker and docker-compose to minimise the hassle of setting up frontend, backend and database servers.

The best part though is of course kept till last.

Using Docker volumes, the development files for the applications sit on your local computer file system, however the applications run within docker and reload on changes. This means you can switch between your code and browser in seconds and see the changes and not have to worry about manually compiling before seeing your changes. Node Modules have their own volume inside the container, so your local ones won't be affected.

On the server side this is accomplished with nodemon and on the clientside with ng serve using page reloading.

Each container also has an internal volume for node_modules so there are no issues with cross-OS compatibility.

If you ever get disconnected from your docker sessions afer starting them up, you can type takeoff start again and you will reconnect to see any log output.

Why Takeoff?

Takeoff is designed to cut out those first few crucial hours where you are setting up your project environment, such as babel and webpack configurations, user authentication or even just selecting a framework. It's perfect for hackdays, rapid prototypes, or teaching new coders by having a pre-configured environment in just 4 simple commands.

It cuts out the scary/annoying bit and gets right to the fun bit!

System Dependencies

This software has some dependencies, and currently has only been fully tested on Linux using Docker Community Edition.

First install this, once installed you will have the docker and docker-compose commands. You also need git and it's recommended you have node >= 10.0.0.

Up and running

You should now have a server running at http://localhost. You can access the API via http://localhost/api.

The default blueprint (takeoff-blueprint-basic is installed as the default environment in the env and blueprints folders.

After installing, you will have this folder structure in your Takeoff environment:

    -|- .takeoffrc
     |- blueprints/default # The basic blueprint that Takeoff ships
     |- project/default # The default environment installed
        |- takeoff.md
        |- env # Folders with the source code you can change
            |- api # This is the Hapi API Server
            |- frontend-app # Angular application
            |- nginx # Nginx configuration
        |- docker # This is where all the docker configurations are kept
            |- docker-compose.yml # The glue file for your services
            |- api # This is the Hapi API Server
            |- frontend-app # Angular app docker file
            |- nginx # Nginx configuration

Blueprint Cache

When you install a new blueprint, it is cached in the blueprints folder; this way when you create a new project below it uses your local copy. If you want to update a blueprint, you can type takeoff blueprint:update [name]. The default one is installed as basic for now. You can also install new blueprints via takeoff blueprint:add [name] [git-url].

.takeoffrc

The .takeoffrc file is a JSON configuration file that is used to define the root folder of an environment. When takeoff runs, it will parse this file and provide it as properties available to commands. The file can also have the .json extension if you prefer.

Creating new projects

When you want to create a new environment you can type:

takeoff new [environment] [blueprint-name] --blueprint-url
# Both blueprints here are optional, the first uses the local cache the second specifies a remote
takeoff start [environment]

This will start up your new named environment using the default blueprint if no name is specified. It's good to make sure you have stopped any other environments running unless you have changed ingress port assignments.

Custom Commands

Takeoff supports custom commands with it's drop-in and easy-to-use API. These are JavaScript or TypeScript files that give you access to do tasks within a Takeoff project, such as custom installers or seeders.

By adding a command to the environments command folder with a group and command option, it becomes available to users of your blueprint, and can be run as part of your setup too.

You can checkout the Custom Commands Documentation for more details.

Platform Support

Currently only Linux is fully tested and supported out of the box, but support for other OS is coming (testers and contributors welcome!). There is a page for Windows Users to provide extra information in the quest to get it working.

Documentation

References