diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..f5189a89 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @bobheadxi diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..74cec18e --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,159 @@ +# Contributing + +This document outlines key considerations and tips for anyone contributing to Inertia. + +- [Opening an Issue](#opening-an-issue) +- [Submitting a Pull Request](#submitting-a-pull-request) +- [Development Tips](#development-tips) + +------ + +# Opening an Issue + +Please do a quick search of past issues before opening a ticket. If working on a ticket, please assign it to yourself or leave a comment saying you are working on it. If you have decide to stop working on a ticket before it gets resolved, please un-assign yourself. + +# Submitting a Pull Request + +All pull requests should be connected to one or more issues. Please try to fill out the pull request template to the best of your ability and use a clear, descriptive title. + +At the very least, all pull requests need to pass our Travis builds and receive an approval from a reviewer. Please include tests whenever possible. + +# Development Tips + +This section outlines the various tools available to help you get started developing Inertia. Run `make ls` to list all the Makefile shortcuts available. + +If you would like to contribute, feel free to comment on an issue or make one and open up a pull request! + +## Setup + +First, [install Go](https://golang.org/doc/install#install) and grab Inertia's source code: + +```bash +$> go get -u github.com/ubclaunchpad/inertia +``` + +We use [dep](https://github.com/golang/dep) for managing Golang dependencies, and [npm](https://www.npmjs.com) to manage dependencies for Inertia's React web app. Make sure both are installed before running the following commands. + +```bash +$> dep ensure # Inertia CLI and daemon dependencies +$> make web-deps # Inertia Web dependencies +$> make RELEASE=test # installs Inertia build tagged as "test" +$> inertia --version # check what version you have installed +``` + +A build tagged as `test` allows you to use `make testdaemon` for local development. See the next section for more details. + +Alternatively, you can manually edit `.inertia.toml` to use your desired daemon version - see the [Release Streams](#release-streams) documentation for more details. + +Note that if you install Inertia using these commands or any variation of `go install`, you may have to remove the binary using `go clean -i github.com/ubclaunchpad/inertia` to go back to using an Inertia CLI installed using Homebrew. To go back to a `go install`ed version of Inertia, you need to run `brew uninstall inertia`. + +## Repository Structure + +The codebase for the CLI is in the root directory. This code should only include the user interface - all client-based logic and functionality should go into the client. + +### Client + +The Inertia client manages all clientside functionality. The client codebase is in `client/`. + +### Daemon + +The Inertia daemon manages all serverside functionality. The daemon codebase is in `daemon/inertia`. + +### Inertia Web + +The Inertia Web application provides a web interface to manage an Inertia deployment. The web application codebase is in `daemon/web`. + +## Testing and Locally Deploying + +You will need Docker installed and running to run the Inertia test suite, which includes a number of integration tests. + +```bash +$> make test-all # test against ubuntu:latest +$> make test-all VPS_OS=ubuntu VERSION=14.04 # test against ubuntu:14.04 +``` + +You can also manually start a container that sets up a mock VPS for testing: + +```bash +$> make testenv VPS_OS=ubuntu VERSION=16.04 +# This defaults to ubuntu:lastest without args. +# Note the location of the key that is printed and use that when +# adding your local remote. +``` + +You can [SSH into this testvps container](https://bobheadxi.github.io/dockerception/#ssh-services-in-docker) and otherwise treat it just as you would treat a real VPS: + +```bash +$> cd /path/to/my/dockercompose/project +$> inertia init +$> inertia remote add local +# PEM file: inertia/test/keys/id_rsa, User: 'root', Address: 0.0.0.0 +$> inertia local init +$> inertia local status +``` + +The above steps will pull and use a daemon image from Docker Hub based on the version in your `.inertia.toml`. + +### Daemon + +To use a daemon compiled from source, set your Inertia version in `.inertia.toml` to `test` and run: + +```bash +$> make testdaemon +$> inertia local init +``` + +This will build a daemon image and `scp` it over to the test VPS, and use that image for the daemon when setting up `testvps` using `inertia local init` + +If you run into this error when deploying onto the `testvps`: + +```bash +docker: Error response from daemon: error creating aufs mount to /var/lib/docker/aufs/mnt/fed036790dfcc73da5f7c74a7264e617a2889ccf06f61dc4d426cf606de2f374-init: invalid argument. +``` + +You probably need to go into your Docker settings and add this line to the Docker daemon configuration file: + +```js +{ + ... + "storage-driver" : "aufs" +} +``` + +This sneaky configuration file can be found under `Docker -> Preferences -> Daemon -> Advanced -> Edit File`. + +### Web App + +Inertia Web is a React application. To run a local instance of Inertia Web: + +```bash +$> make web-run +``` + +Make sure you have a local daemon set up for this web app to work - see the previous section for more details. + +## Compiling Bash Scripts + +To bootstrap servers, some bash scripting is often involved, but we'd like to avoid shipping bash scripts with our go binary. So we use [go-bindata](https://github.com/jteeuwen/go-bindata) to compile shell scripts into our go executables. + +```bash +$> go get -u github.com/jteeuwen/go-bindata/... +``` + +If you make changes to the bootstrapping shell scripts in `client/bootstrap/`, convert them to `Assets` by running: + +```bash +$> make bootstrap +``` + +Then use your asset! + +```go +shellScriptData, err := Asset("cmd/bootstrap/myshellscript.sh") +if err != nil { + log.Fatal("No asset with that name") +} + +// Optionally run shell script over SSH. +result, _ := remote.RunSSHCommand(string(shellScriptData)) +``` diff --git a/.static/inertia-init.png b/.static/inertia-init.png new file mode 100644 index 00000000..33d02ecb Binary files /dev/null and b/.static/inertia-init.png differ diff --git a/Makefile b/Makefile index 744edb65..15e89a47 100644 --- a/Makefile +++ b/Makefile @@ -43,12 +43,12 @@ test-all: test-integration: make testenv VPS_OS=$(VPS_OS) VPS_VERSION=$(VPS_VERSION) make testdaemon - go test ./... -v -ldflags "-X main.Version=test" --cover + go test ./... -v -run 'Integration' -ldflags "-X main.Version=test" --cover # Run integration tests verbosely without recreating test VPS test-integration-fast: make testdaemon - go test ./... -run -v Integration -ldflags "-X main.Version=test" --cover + go test ./... -v -run 'Integration' -ldflags "-X main.Version=test" --cover # Create test VPS testenv: diff --git a/README.md b/README.md index a2aba80c..805a39cf 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,17 @@

Built Status + alt="Build Status" /> Clean code + + + + @@ -23,25 +27,41 @@ ---------------- -Inertia is a cross-platform command line tool that simplifies setup and management of automated project deployment on any virtual private server. It aims to provide the ease and flexibility of services like Heroku without the complexity of Kubernetes while still giving users full control over their projects. +Inertia is a simple cross-platform command line application that enables effortless setup and management of continuous, automated deployment on any virtual private server. It is built and maintained with :heart: by [UBC Launch Pad](https://www.ubclaunchpad.com/). + +

+ +

+ +| | Main Features | +----|----------------- +🚀 | Simple setup from your computer without ever having to manually SSH into your remote +🍰 | Use any Linux-based remote virtual private server platform you want +⚒ | Deploy a wide range of supported project types (including docker-compose and Heroku buildpacks) +🚄 | Have your project automatically updated as soon as you `git push` +🛂 | Start up and shut down your deployment with ease +📚 | Monitor your deployed application's logs straight from your command line +🏷 | Configure deployment to your liking with branch settings and more + +---------------- -- [Usage](#package-usage) +- [Getting Started](#package-getting-started) - [Setup](#setup) - [Continuous Deployment](#continuous-deployment) - [Deployment Management](#deployment-management) - [Release Streams](#release-streams) - [Motivation and Design](#bulb-motivation-and-design) -- [Development](#construction-development) +- [Contributing](#books-contributing) -# :package: Usage +# :package: Getting Started -All you need to get started is a docker-compose project, the Inertia CLI, and access to a virtual private server. To install the CLI using [Homebrew](https://brew.sh): +All you need to get started is a [compatible project](https://github.com/ubclaunchpad/inertia/wiki/Project-Compatibility), the Inertia CLI, and access to a virtual private server. The CLI can be installed using [Homebrew](https://brew.sh): ```bash $> brew install ubclaunchpad/tap/inertia ``` -For other platforms, you can also [download the appropriate binary from the Releases page](https://github.com/ubclaunchpad/inertia/releases) or [install Inertia from source](#installing-from-source). +For other platforms, you can [download the appropriate binary from the Releases page](https://github.com/ubclaunchpad/inertia/releases). ## Setup @@ -117,7 +137,9 @@ Add some bling to your Inertia-deployed project :sunglasses: # :bulb: Motivation and Design -At [UBC Launch Pad](http://www.ubclaunchpad.com), we are frequently changing hosting providers based on available funding and sponsorship. Inertia is a project to develop an in-house continuous deployment system to make deploying applications simple and painless, regardless of the hosting provider. +[UBC Launch Pad](http://www.ubclaunchpad.com) 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. Inertia is a project to develop an in-house deployment system to make setting up continuously deployed applications simple and painless, regardless of the hosting provider. The primary design goals of Inertia are to: @@ -137,136 +159,6 @@ The deployment daemon runs persistently in the background on the server, receivi 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](https://bobheadxi.github.io/dockerception/#docker-in-docker). 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](https://bobheadxi.github.io/dockerception/#docker-compose-in-docker) to build and deploy user projects. -# :construction: Development - -This section outlines the various tools available to help you get started developing Inertia. Run `make ls` to list all the Makefile shortcuts available. - -If you would like to contribute, feel free to comment on an issue or make one and open up a pull request! - -## Installing from Source - -First, [install Go](https://golang.org/doc/install#install) and grab Inertia's source code: - -```bash -$> go get -u github.com/ubclaunchpad/inertia -``` - -We use [dep](https://github.com/golang/dep) for managing Golang dependencies, and [npm](https://www.npmjs.com) to manage dependencies for Inertia's React web app. Make sure both are installed before running the following commands. - -```bash -$> dep ensure # Inertia CLI and daemon dependencies -$> make web-deps # Inertia Web dependencies -``` - -For usage, it is highly recommended that you use a [tagged build](https://github.com/ubclaunchpad/inertia/releases) to ensure compatibility between the CLI and your Inertia daemon. - -```bash -$> git checkout $VERSION -$> make inertia-tagged # installs a tagged version of Inertia -$> inertia --version # check what version you have installed -``` - -Alternatively, you can manually edit `.inertia.toml` to use your desired daemon version - see the [Release Streams](#release-streams) documentation for more details. - -Note that if you install Inertia using these commands or any variation of `go install`, you may have to remove the binary using `go clean -i github.com/ubclaunchpad/inertia` to go back to using an Inertia CLI installed using Homebrew. To go back to a `go install`ed version of Inertia, you need to run `brew uninstall inertia`. - -For development, you should install a build tagged as `test` so that you can make use `make testdaemon` for local development. See the next section for more details. - -```bash -$> make RELEASE=test # installs current Inertia build and mark as "test" -``` - -## Testing and Locally Deploying - -You will need Docker installed and running to run the Inertia test suite, which includes a number of integration tests. - -```bash -$> make test-all # test against ubuntu:latest -$> make test-all VPS_OS=ubuntu VERSION=14.04 # test against ubuntu:14.04 -``` - -You can also manually start a container that sets up a mock VPS for testing: - -```bash -$> make testenv VPS_OS=ubuntu VERSION=16.04 -# This defaults to ubuntu:lastest without args. -# Note the location of the key that is printed and use that when -# adding your local remote. -``` +# :books: Contributing -You can [SSH into this testvps container](https://bobheadxi.github.io/dockerception/#ssh-services-in-docker) and otherwise treat it just as you would treat a real VPS: - -```bash -$> cd /path/to/my/dockercompose/project -$> inertia init -$> inertia remote add local -# PEM file: inertia/test/keys/id_rsa, User: 'root', Address: 0.0.0.0 -$> inertia local init -$> inertia local status -``` - -The above steps will pull and use a daemon image from Docker Hub based on the version in your `.inertia.toml`. - -### Daemon - -To use a daemon compiled from source, set your Inertia version in `.inertia.toml` to `test` and run: - -```bash -$> make testdaemon -$> inertia local init -``` - -This will build a daemon image and `scp` it over to the test VPS, and use that image for the daemon when setting up `testvps` using `inertia local init` - -If you run into this error when deploying onto the `testvps`: - -```bash -docker: Error response from daemon: error creating aufs mount to /var/lib/docker/aufs/mnt/fed036790dfcc73da5f7c74a7264e617a2889ccf06f61dc4d426cf606de2f374-init: invalid argument. -``` - -You probably need to go into your Docker settings and add this line to the Docker daemon configuration file: - -```js -{ - ... - "storage-driver" : "aufs" -} -``` - -This sneaky configuration file can be found under `Docker -> Preferences -> Daemon -> Advanced -> Edit File`. - -### Web App - -Inertia Web is a React application. To run a local instance of Inertia Web: - -```bash -$> make web-run -``` - -Make sure you have a local daemon set up for this web app to work - see the previous section for more details. - -## Compiling Bash Scripts - -To bootstrap servers, some bash scripting is often involved, but we'd like to avoid shipping bash scripts with our go binary. So we use [go-bindata](https://github.com/jteeuwen/go-bindata) to compile shell scripts into our go executables. - -```bash -$> go get -u github.com/jteeuwen/go-bindata/... -``` - -If you make changes to the bootstrapping shell scripts in `client/bootstrap/`, convert them to `Assets` by running: - -```bash -$> make bootstrap -``` - -Then use your asset! - -```go -shellScriptData, err := Asset("cmd/bootstrap/myshellscript.sh") -if err != nil { - log.Fatal("No asset with that name") -} - -// Optionally run shell script over SSH. -result, _ := remote.RunSSHCommand(string(shellScriptData)) -``` +Any contribution (pull requests, feedback, bug reports, ideas, etc.) is welcome! Please see our [contribution guide](https://github.com/ubclaunchpad/inertia/blob/master/.github/CONTRIBUTING.md) for more details and development tips.