README

Inertia

An effortless, self-hosted continuous deployment platform.

Build Status Clean code go.pkg.dev documentation available inertia CLI downloads Latest release


Usage · Motivation & Design · Contributing · Wiki



Inertia is a user-friendly, cross-platform command line application and serverside agent that enables quick and easy setup and management of continuous, automated deployment of a variety of project types on any virtual private server. The project is used, built, and maintained with ❤️ by UBC Launch Pad, UBC's student-run software engineering club.

Main Features
🚀 Simple to use - set up a deployment from your computer without ever having to manually SSH into your remote
🍰 Cloud-agnostic - use any Linux-based remote virtual private server provider you want
Versatile project support - deploy any Dockerfile or docker-compose project
🚄 Continuous deployment - Webhook integrations for GitHub, GitLab, and Bitbucket means your project can be automatically updated, rebuilt, and deployed as soon as you git push
🛂 In-depth controls - start up, shut down, and monitor your deployment with ease from the command line or using Inertia's REST API
🏷 Flexible configuration - branch deployment, environment variables, easy file transfer for configuration files, build settings, and more
📦 Built-in provisioning - easily provision and set up VPS instances for your project with supported providers such as Amazon Web Services using a single command
👥 Built for teams - provide shared access to an Inertia deployment by adding users
🔑 Secure - secured with access tokens and HTTPS across the board, as well as features like 2FA for user logins

📦 Usage

Check out our new Inertia Usage Guide to get started with using Inertia for your project! The guide will walk you through installing Inertia, setting up a project, deploying to a remote, managing your deployment, and advanced usage tips.

Why Use Inertia?

If you...

  • want a simple utility to quickly build and deploy the latest iterations of your projects
  • are new to the concept of "deployment" and related tooling
  • are on a tight budget and need to switch between cloud providers as your free trials run out
  • want some lightweight team features for managing your deployment

Inertia might be for you! For example, UBC Launch Pad teams have used Inertia to set up automated deployments for projects like Rocket 2 and Bumper, and nwPlus used Inertia to stage previews of the nwHacks 2019 website during development.



💡 Motivation and Design

UBC Launch Pad is a student-run software engineering club at the University of British Columbia that aims to provide students with a community where they can work together to build a all sorts of cool projects, ranging from mobile apps and web services to cryptocurrencies and machine learning applications.

Many of our projects rely on hosting providers for deployment. Unfortunately we frequently change hosting providers based on available funding and sponsorship, meaning our projects often need to be redeployed. On top of that, deployment itself can already be a frustrating task, especially for students with little to no experience setting up applications on remote hosts. Inertia is a project we started to address these problems, with the goal of developing an in-house deployment system that can make setting up continuously deployed applications simple and painless, regardless of the hosting provider.

The primary design goals of Inertia are to:

  • minimize setup time for new projects
  • maximise compatibility across different client and VPS platforms
  • offer an easy-to-learn interface for managing deployed applications
How It Works

There is a detailed Medium post that goes over the project, its motivations, the design choices we made, and Inertia's implementation. The team has also made a few presentations about Inertia that go over its design in some more detail:

In summary, Inertia consists of two major components: a deployment daemon and a command line interface.

The deployment daemon runs persistently in the background on the server, receiving webhook events from GitHub whenever new commits are pushed. The CLI provides an interface to adjust settings and manage the deployment - this is done through HTTPS requests to the daemon, authenticated using JSON web tokens generated by the daemon. Remote configuration is stored locally in .inertia.toml.

Inertia is set up serverside by executing a script over SSH that installs Docker and starts an Inertia daemon image with access to the host Docker socket. This Docker-in-Docker configuration gives the daemon the ability to start up other containers alongside it, rather than within it, as required. Once the daemon is set up, we avoid using further SSH commands and execute Docker commands through Docker's Golang API. Instead of installing the docker-compose toolset, we use a docker-compose image to build and deploy user projects.



📚 Contributing

Any contribution (pull requests, feedback, bug reports, ideas, etc.) is welcome!

Please see our contribution guide for contribution guidelines as well as a detailed guide to help you get started with Inertia's codebase.


0 1 2 3 4 5 6 7

Expand ▾ Collapse ▴

Documentation

Overview

    Inertia is the command line interface that helps you set up your remote for continuous deployment and allows you to manage your deployment through configuration options and various commands.

    This document contains basic usage instructions, but a new usage guide is also available here: https://inertia.ubclaunchpad.com/

    Inertia can be installed in several ways:

    # Mac users
    brew install ubclaunchpad/tap/inertia
    
    # Windows users
    scoop bucket add ubclaunchpad https://github.com/ubclaunchpad/scoop-bucket
    scoop install inertia
    

    Users of other platforms can install the Inertia CLI from the Releases page, found here: https://github.com/ubclaunchpad/inertia/releases/latest

    To help with usage, most relevant documentation can be seen by using the --help flag on any command:

    inertia --help
    inertia init --help
    inertia [remote] up --help
    

    Documentation can also be triggered by simply entering a command without the prerequisite arguments or additional commands:

    inertia remote               # documentation about remote configuration
    

    Inertia has two "core" sets of commands - one that primarily handles local configuration, and one that allows you to control your remote VPS instances and their associated deployments.

    For local configuration, most commands will build off of the root "inertia ..." command. For example, a typical set of commands to set up a project might look like:

    inertia init                 # initiates Inertia configuration
    inertia remote add my_cloud  # adds configuration for a remote VPS instance
    

    The other set of commands are based on a remote VPS configuration, and the available commands can be seen by running:

    inertia [remote] --help
    

    In the previous example, the next steps to set up a deployment might be:

    inertia my_cloud init        # bootstraps remote and installs Inertia daemon
    inertia my_cloud up          # deploys your project
    

    Some of these commands offer a --stream flag that allows you to view realtime log feedback from the daemon.

    More documentation on Inertia, how it works, and how to use it can be found in the project repository: https://github.com/ubclaunchpad/inertia/tree/master

    Source Files

    Directories

    Path Synopsis
    Package api contains definitions for Inertia API requests and responses
    Package api contains definitions for Inertia API requests and responses
    Package cfg provides configuration structs and types
    Package cfg provides configuration structs and types
    Package client provides the interface through which Inertia communicates with a serverside daemon
    Package client provides the interface through which Inertia communicates with a serverside daemon
    bootstrap
    Package bootstrap provides Inertia's remote bootstrapping script, based off of inertia/client.Client
    Package bootstrap provides Inertia's remote bootstrapping script, based off of inertia/client.Client
    runner
    Package runner provides the Inertia client's low-level SSH command runner
    Package runner provides the Inertia client's low-level SSH command runner
    runner/mocks
    Package mocks provides mocked implmentations of interfaces in client/runner Code generated by counterfeiter.
    Package mocks provides mocked implmentations of interfaces in client/runner Code generated by counterfeiter.
    cmd
    Package cmd contains Inertia's command-line interface components and logic
    Package cmd contains Inertia's command-line interface components and logic
    core
    Package core provides a parent class for the root 'inertia' command
    Package core provides a parent class for the root 'inertia' command
    core/utils/input
    Package input provides input parsing utilities for the Inertia CLI
    Package input provides input parsing utilities for the Inertia CLI
    core/utils/out
    Package out provides out utilities for the Inertia CLI
    Package out provides out utilities for the Inertia CLI
    project
    Package projectcmd implements the 'inertia project' subcommands
    Package projectcmd implements the 'inertia project' subcommands
    provision
    Package provisioncmd implements the 'inertia provision' subcommands
    Package provisioncmd implements the 'inertia provision' subcommands
    remote
    Package remotecmd implements the 'inertia remote' subcommands
    Package remotecmd implements the 'inertia remote' subcommands
    remotes
    Package remotescmd implements the 'inertia [remote]' subcommands
    Package remotescmd implements the 'inertia [remote]' subcommands
    Package common provides utilities, shared variables, and types for both the client and the daemon
    Package common provides utilities, shared variables, and types for both the client and the daemon
    contrib
    inertia-completions
    Inertia-completions is a tool for generating Inertia shell completions.
    Inertia-completions is a tool for generating Inertia shell completions.
    inertia-docgen
    Inertia-docgen is a tool for generating Inertia command documentation.
    Inertia-docgen is a tool for generating Inertia command documentation.
    inertia-publish
    Inertia-publish is a tool for helping publish Inertia releases to various distribution channels.
    Inertia-publish is a tool for helping publish Inertia releases to various distribution channels.
    daemon
    inertiad
    Inertiad is Inertia's daemon component.
    Inertiad is Inertia's daemon component.
    inertiad/auth
    Package auth provides the Inertia daemon's authentication and security framework
    Package auth provides the Inertia daemon's authentication and security framework
    inertiad/build
    Package build implements Inertia's build procedures
    Package build implements Inertia's build procedures
    inertiad/build/mocks
    Code generated by counterfeiter.
    Code generated by counterfeiter.
    inertiad/cfg
    Package cfg provides the daemon's core configuration
    Package cfg provides the daemon's core configuration
    inertiad/containers
    Package containers provides utilities for interacting with Docker containers
    Package containers provides utilities for interacting with Docker containers
    inertiad/crypto
    Package crypto provides functions for managing encryption, keys, etc.
    Package crypto provides functions for managing encryption, keys, etc.
    inertiad/daemon
    Package daemon provides Inertiad's core server and API
    Package daemon provides Inertiad's core server and API
    inertiad/git
    Package git provides functions for interacting with git repositories
    Package git provides functions for interacting with git repositories
    inertiad/log
    Package log provides logging utilities
    Package log provides logging utilities
    inertiad/notify
    Package notify provides experimental support for notifications providers.
    Package notify provides experimental support for notifications providers.
    inertiad/notify/mocks
    Code generated by counterfeiter.
    Code generated by counterfeiter.
    inertiad/project
    Package project contains Inertia's build and project management code
    Package project contains Inertia's build and project management code
    inertiad/project/mocks
    Code generated by counterfeiter.
    Code generated by counterfeiter.
    inertiad/res
    Package res provides simple HTTP response primitives
    Package res provides simple HTTP response primitives
    inertiad/util
    Package util provides miscellaneous utility functions
    Package util provides miscellaneous utility functions
    inertiad/webhook
    Package webhook contains Inertia's webhook parsing code
    Package webhook contains Inertia's webhook parsing code
    Package local provides access to local assets for the CLI
    Package local provides access to local assets for the CLI
    git
    Package git provides utilities for interacting with git.
    Package git provides utilities for interacting with git.
    Package provision contains Inertia's VPS instance provisioning API
    Package provision contains Inertia's VPS instance provisioning API
    internal
    tools
    Package tools is a package is set up as recommended in [this guide](https://github.com/go-modules-by-example/index/blob/master/010_tools/README.md).
    Package tools is a package is set up as recommended in [this guide](https://github.com/go-modules-by-example/index/blob/master/010_tools/README.md).