diff --git a/.gitattributes b/.gitattributes
index 62cce8ee..5bbdd765 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -6,3 +6,6 @@
*.png binary
*.jpg binary
*.pdf binary
+
+# Mark docs as generated
+docs/* linguist-generated
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug-report.md
similarity index 100%
rename from .github/ISSUE_TEMPLATE/bug_report.md
rename to .github/ISSUE_TEMPLATE/bug-report.md
diff --git a/.github/ISSUE_TEMPLATE/doc-issue.md b/.github/ISSUE_TEMPLATE/doc-issue.md
new file mode 100644
index 00000000..5087acd3
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/doc-issue.md
@@ -0,0 +1,15 @@
+---
+name: Documentation issue
+about: Let us know if something is wrong with our documentation!
+title: 'docs: '
+labels: 'type: docs :book:'
+assignees: ''
+
+---
+
+**Describe the issue**
+A clear and concise description of what the issue is.
+
+**Additional context**
+Add any other context about the problem here, such as screenshots and links to
+relevant documentation.
diff --git a/.gitignore b/.gitignore
index 3b12a49d..e0399deb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,3 +40,6 @@ public/
# JetBrains
.idea
+
+# Doc build
+docs_build
diff --git a/.scripts/build_docs.sh b/.scripts/build_docs.sh
new file mode 100644
index 00000000..46a398cb
--- /dev/null
+++ b/.scripts/build_docs.sh
@@ -0,0 +1,68 @@
+#! /bin/bash
+
+set -e
+
+###
+# This script is a wonderful hack I made to get around the fact that Slate
+# (https://github.com/lord/slate) documentation recommends that you fork the
+# repository and then write your documentation inside it.
+#
+# To convert Slate into a pure "doc builder", this script does a few things:
+# * clone my (Robert's) fork of Slate into temporary /docs_build
+# * write and sed custom configuration into the repository
+# * symlink our doc assets (primarily in /docs_src, but also a few image assets
+# from .static) into the cloned Slate repository
+# * build the documentation into /docs, which is deployed by GH-pages
+#
+# The symlink + config hacks also allows live-reload local dev deployment (using
+# the 'make run-docs' target in /Makefile).
+###
+
+# Get Slate
+echo "[INFO] Getting Slate"
+mkdir -p docs_build
+cd docs_build
+if [ ! -d slate ]; then
+ # Using Robert's fork for now, for extra swag and configuration options not
+ # available in vanilla Slate
+ git clone https://github.com/bobheadxi/slate.git
+else
+ echo "[INFO] Slate already present in docs_build/slate"
+fi
+
+# Add custom config to Slate
+echo "[INFO] Hacking Slate configuration"
+TEMPLATE_FILES_WATCH="files.watch :source, path: File.join(root, '../../docs_src')"
+if ! grep -q "$TEMPLATE_FILES_WATCH" slate/config.rb ; then
+ # We want to symlink our doc assets into the repo, so to retain live reload
+ # functionality, we want the generator Slate uses (Middleman) to watch our
+ # symlink sources for changes too
+ echo "$TEMPLATE_FILES_WATCH" \
+ >> slate/config.rb
+fi
+if ! grep -q "<%= favicon_tag 'favicon.ico' %>" slate/source/layouts/layout.erb ; then
+ # This inserts a favicon reference into the
element of the
+ # documentation layout
+ sed -i '' '/
/a\
+ <%= favicon_tag '\''favicon\.ico'\'' %>
+ ' slate/source/layouts/layout.erb
+fi
+
+# Set up Slate for build
+echo "[INFO] Linking assets"
+ln -fs "$(dirname "$(pwd)")"/docs_src/index.html.md \
+ slate/source/index.html.md
+ln -fs "$(dirname "$(pwd)")"/docs_src/stylesheets/_variables.scss \
+ slate/source/stylesheets/_variables.scss
+ln -fs "$(dirname "$(pwd)")"/.static/inertia.png \
+ slate/source/images/logo.png
+ln -fs "$(dirname "$(pwd)")"/.static/favicon.ico \
+ slate/source/images/favicon.ico
+echo "[INFO] Installing Slate dependencies"
+cd slate
+bundle install
+
+# Execute build
+echo "[INFO] Building documentation"
+rm -rf docs
+bundle exec middleman build --clean --build-dir=../../docs
diff --git a/.static/favicon.ico b/.static/favicon.ico
new file mode 100644
index 00000000..ffd5befb
Binary files /dev/null and b/.static/favicon.ico differ
diff --git a/.static/inertia.png b/.static/inertia.png
new file mode 100644
index 00000000..3723af17
Binary files /dev/null and b/.static/inertia.png differ
diff --git a/CNAME b/CNAME
index 8aef0332..afc790f2 100644
--- a/CNAME
+++ b/CNAME
@@ -1 +1 @@
-inertia.ubclaunchpad.com
\ No newline at end of file
+inertia.ubclaunchpad.com
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a1d22aa6..a64b742c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -178,6 +178,18 @@ $> make web-run # run local instance of application
Make sure you have a local daemon set up for this web app to work - see the previous section for more details.
+### Documentation
+
+Our [usage documentation website]() is built with [Slate](https://github.com/lord/slate).
+The builds are in `/docs`, but the documentation source is in `/docs_src`.
+
+To build and deploy the documentation locally:
+
+```bash
+$> make docs
+$> make run-docs # visit http://localhost:4567/
+```
+
## Setting up a Testing Environment
You will need Docker installed and running to run whole the Inertia test suite,
diff --git a/Makefile b/Makefile
index 9c76910f..7031f55d 100644
--- a/Makefile
+++ b/Makefile
@@ -16,6 +16,7 @@ ls:
clean: testenv-clean
go clean -testcache
rm -f ./inertia
+ rm -rf ./docs_build
find . -type f -name inertia.\* -exec rm {} \;
# Install all dependencies
@@ -182,3 +183,11 @@ web-run-sandbox:
.PHONY: web-build
web-build:
(cd ./daemon/web; npm install --production; npm run build)
+
+.PHONY: docs
+docs:
+ sh .scripts/build_docs.sh
+
+.PHONY: run-docs
+run-docs:
+ ( cd docs_build/slate ; bundle exec middleman server --verbose )
diff --git a/README.md b/README.md
index 279afb8e..1255fc85 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@
- Getting Started ·
+ Usage ·
Motivation & Design ·
Contributing ·
Wiki
@@ -71,107 +71,24 @@ Inertia is a simple cross-platform command line application that enables quick a
-# :package: Getting Started
+# :package: Usage
-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.
+Check out our new **[Inertia Usage Guide](https://inertia.ubclaunchpad.com)** 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.
-MacOS users can install the CLI using [Homebrew](https://brew.sh):
+### Why Use Inertia?
-```bash
-$> brew install ubclaunchpad/tap/inertia
-```
+If you...
-Windows users can install the CLI using [Scoop](http://scoop.sh):
+* 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 not deploying to production
+* 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
-```bash
-$> scoop bucket add ubclaunchpad https://github.com/ubclaunchpad/scoop-bucket
-$> scoop install inertia
-```
-
-For other platforms, you can [download the appropriate binary from the Releases page](https://github.com/ubclaunchpad/inertia/releases).
-
-### Setup
-
-Initializing a project for use with Inertia only takes a few simple steps:
-
-```bash
-$> inertia init
-```
-
-#### Using an Existing Remote
-
-To use an existing host, you must first add it to your Inertia configuration and initialize it - this will install Inertia on your remote.
-
-```bash
-$> inertia remote add $VPS_NAME
-$> inertia $VPS_NAME init
-$> inertia $VPS_NAME status
-# Confirms that the daemon is online and accepting requests
-```
-
-See our [wiki](https://github.com/ubclaunchpad/inertia/wiki/VPS-Compatibility) for more details on VPS platform compatibility.
-
-#### Provisioning a New Remote
-
-Inertia offers some tools to easily provision a new VPS instance and set it up for Inertia. For example, to create an EC2 instance and initialize it, just run:
-
-```bash
-$> inertia provision ec2 $VPS_NAME
-$> inertia $VPS_NAME status
-```
-
-### Deployment Management
-
-To manually deploy your project, you must first grant Inertia permission to clone your repository. This can be done by adding the GitHub Deploy Key that is displayed in the output of `inertia $VPS_NAME init` to your repository settings:
-
-```bash
-GitHub Deploy Key (add here https://www.github.com//settings/keys/new):
-ssh-rsa <...>
-```
-
-Once this is done, you can use Inertia to bring your project online on your remote VPS:
-
-```bash
-$> inertia $VPS_NAME up
-```
-
-Run `inertia $VPS_NAME --help` to see the other commands Inertia offers for managing your deployment.
-
-Inertia also offers a web application - this can be accessed at `https://$ADDRESS:4303/web` once users have been added through the `inertia $VPS_NAME user` commands.
-
-### Continuous Deployment
-
-To enable continuous deployment, you need the webhook URL that is printed during `inertia $VPS_NAME init`:
-
-```bash
-GitHub WebHook URL (add here https://www.github.com//settings/hooks/new):
-http://myhost.com:4303/webhook
-Github WebHook Secret: inertia
-```
-
-The daemon will accept POST requests from GitHub at the URL provided. Add this webhook URL in your GitHub settings area (at the URL provided) so that the daemon will receive updates from GitHub when your repository is updated. Once this is done, the daemon will automatically build and deploy any changes that are made to the deployed branch.
-
-### Release Streams
-
-The version of Inertia you are using can be seen in Inertia's `.inertia.toml` configuration file, or by running `inertia --version`. The version in `.inertia.toml` is used to determine what version of the Inertia daemon to use when you run `inertia $VPS_NAME init`.
-
-You can manually change the daemon version used by editing the Inertia configuration file. If you are building from source, you can also check out the desired version and run `make inertia-tagged` or `make RELEASE=$STREAM`. Inertia daemon releases are tagged as follows:
-
-- `v0.x.x` denotes [official, tagged releases](https://github.com/ubclaunchpad/inertia/releases) - these are recommended.
-- `latest` denotes the newest builds on `master`.
-- `canary` denotes experimental builds used for testing and development - do not use this.
-
-The daemon component of an Inertia release can be patched separately from the CLI component - see our [wiki](https://github.com/ubclaunchpad/inertia/wiki/Daemon-Releases) for more details.
-
-### Swag
-
-Add some bling to your Inertia-deployed project :sunglasses:
-
-[![Deployed with Inertia](https://img.shields.io/badge/deploying%20with-inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
-
-```
-[![Deployed with Inertia](https://img.shields.io/badge/deploying%20with-inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
-```
+Inertia might be for you!
diff --git a/docs/fonts/slate.eot b/docs/fonts/slate.eot
new file mode 100644
index 00000000..13c4839a
Binary files /dev/null and b/docs/fonts/slate.eot differ
diff --git a/docs/fonts/slate.svg b/docs/fonts/slate.svg
new file mode 100644
index 00000000..5f349823
--- /dev/null
+++ b/docs/fonts/slate.svg
@@ -0,0 +1,14 @@
+
+
+
diff --git a/docs/fonts/slate.ttf b/docs/fonts/slate.ttf
new file mode 100644
index 00000000..ace9a46a
Binary files /dev/null and b/docs/fonts/slate.ttf differ
diff --git a/docs/fonts/slate.woff b/docs/fonts/slate.woff
new file mode 100644
index 00000000..1e72e0ee
Binary files /dev/null and b/docs/fonts/slate.woff differ
diff --git a/docs/fonts/slate.woff2 b/docs/fonts/slate.woff2
new file mode 100644
index 00000000..7c585a72
Binary files /dev/null and b/docs/fonts/slate.woff2 differ
diff --git a/docs/images/aws-ec2-iam-add.png b/docs/images/aws-ec2-iam-add.png
new file mode 100644
index 00000000..05335f0c
Binary files /dev/null and b/docs/images/aws-ec2-iam-add.png differ
diff --git a/docs/images/aws-ec2-iam-perm.png b/docs/images/aws-ec2-iam-perm.png
new file mode 100644
index 00000000..8b81b21f
Binary files /dev/null and b/docs/images/aws-ec2-iam-perm.png differ
diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
new file mode 100644
index 00000000..ffd5befb
Binary files /dev/null and b/docs/images/favicon.ico differ
diff --git a/docs/images/logo.png b/docs/images/logo.png
new file mode 100644
index 00000000..3723af17
Binary files /dev/null and b/docs/images/logo.png differ
diff --git a/docs/images/navbar.png b/docs/images/navbar.png
new file mode 100644
index 00000000..df38e90d
Binary files /dev/null and b/docs/images/navbar.png differ
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 00000000..c45675df
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,1033 @@
+
+
+
+
+
+
+
+
+ Inertia Usage Guide
+
+
+
+
+
+
+
+
✈️ Effortless, self-hosted continuous deployment for small teams and projects
+
+
+
+
+
+
+
+
+
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
+
+
+
+
Inertia is a simple cross-platform command line application 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.
+
+
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.
+
+
This site primarily documents how to set up and use Inertia - to learn more
+about the project, check out our GitHub repository!
You can also build Inertia from source, though this requires Golang to be
+installed.
+
+
To verify your installation, try running inertia --help - this should output
+some helpful text about Inertia.
+
+
Run inertia --version to verify that you have the
+latest release.
+
Setup
+
+
This will generate a configuration file inside your repository:
+
+
cd /path/to/project
+inertia init
+
+
To set up Inertia, you must first navigate to your project directory, which
+must be a git repository, and run inertia init to set up configuration. If
+Inertia cannot detect your project type, it will prompt for more information.
+
+
+
+
+
Project Configuration
+
+
An example inertia.toml:
+
+
version="canary"
+project-name="my_project"
+build-type="dockerfile"
+build-file-path="dockerfiles/Dockerfile.web"
+
+# ... other stuff
+
+
+
To change a setting, you can edit the configuration file directly, or run:
+
+
inertia config set${parameter}${new_value}
+
+
Your Inertia configuration is stored in inertia.toml by default. There are
+a few project-wide settings stored here:
+
+
+
+
Parameter
+
Description
+
+
+
+
version
+
This should match the version of your Inertia CLI, which you can see by running inertia --version. It is used to determine which version of the Inertia daemon to use.
+
+
+
project-name
+
The name of the project you are deploying.
+
+
+
build-type
+
This should be either dockerfile or docker-compose, depending on which you are using.
+
+
+
build-file-path
+
Path to your build configuration file, such as Dockerfile or docker-compose.yml, relative to the root of your project.
+
+
+
Deploying Your Project
+
When deploying a project, you typically deploy to a "remote".
+
+
A "remote" is a remote VPS, such as a Google Cloud Compute
+or AWS Elastic Cloud Compute (EC2) instance. These
+are computers in the cloud that will be used to deploy your project, so that
+you don't have to use your own.
+
+
If this is your first time setting up a VPS, jump ahead to the
+Provisioning a Remote section, which will help you set
+up a VPS for Inertia.
+
Using an Existing Remote
+
+
This command will prompt you for the path to your PEM file, your username,
+and the IP address of your remote. These parameters will be used to execute
+SSH commands that set up Inertia on your VPS.
+
+
inertia remote add ${remote_name}
+
+
To use an existing remote, you'll need its address and a PEM key that can be
+used to access it. Inertia will also need a few ports exposed, namely one for
+the Inertia daemon (port 4303 by default) and whatever ports you need for your
+deployed project.
Inertia has integrations with some cloud providers to allow you to easily
+provision a new VPS instance and set it up for Inertia. This includes generating
+key pairs, setting network rules, and initializing the Inertia daemon.
+
+
You can use the --help on the provision command to see what options are
+available.
+
Example: Provisioning an EC2 Instance
+
Elastic Cloud Compute (EC2) is a service provided
+by Amazon Web Services (AWS) that can be used to deploy Inertia projects. It
+offers 750 free EC2 hours a month for your first 12 months,
+which is just enough for 1 EC2 VPS instance. Even after the trial it's pretty
+affordable, and a good choice to get started with.
+
+
+
The IAM users page:
+
+
+
+
To get started, make an account on the AWS website. If you're
+a student, you'll also be eligible for
+yearly free credits, so make sure
+you sign up for that as well.
+
+
Next, you'll want to head over to the
+IAM page of the AWS Management Console.
+IAM stands for "Identity and Access Management", and this is where you'll
+configure programmatic access to your AWS account. Under the "Users" tab, click
+"Add User".
+
+
+
Configuring IAM permissions:
+
+
+
+
This will take you through a brief walkthrough to configure your new IAM user:
+
+
+
Page 1 - make sure you enable Programmatic Access to tell AWS to generate
+access keys for your new user - Inertia will need this.
+
Page 2 - make sure to choose a permission set that allows the user to
+manipulate EC2 resources, such as AmazonEC2FullAccess (this will be
+under the 3rd tab titled "Attach existing policies directly").
+
Page 3 - don't worry about setting tags, as these are typically used for
+organizations with large numbers of users.
+
Page 4 - confirm that you've configured the user correctly
+
Page 5 - you should be shown a Access Key ID and a Secret access key.
+Copy these somewhere safe!
This command says: "provision an ec2 instance called 'my_remote' using
+credentials in my environment and expose port 8080 for my project".
+
+
+
Now that you have your user and access keys all set up, you can provision your
+remote instance! Just set your keys in your
+shell environment
+and use the --from-env flag as in the example to provision a remote using
+those credentials.
+
+
Alternatively, you can save your credentials in your
+AWS credentials file.
+To use these with Inertia, just call the provision ec2 command with the
+--from-profile flag.
+
+
Inertia will just prompt you for the keys if you don't provide them using one
+of the methods above.
+
+
The provisioning command will ask you to choose a
+region
+and an image to
+use. The region should probably be whatever is closest to you, and then you
+should just choose one of the images that Inertia lists as options.
+
+
Inertia will then create an EC2 instance, generate a key pair to give you SSH
+access to the remote, set up network rules, install Inertia's prerequisites on
+your remote, and spin up the Inertia daemon!
For example, the following will change the branch deployed on my_remote
+to dev and print out the new settings:
+
+
inertia remote set my_remote branch dev
+inertia remote show my_remote
+
+
Once you've added a remote, remote-specific settings are available under the
+[remote] section of your Inertia configuration.
+
+
+
+
+
+
Parameter
+
Description
+
+
+
+
IP
+
This is the address of your remote instance. It's how other users will access your deployed project as well!
+
+
+
user
+
The user to use to execute commands as on your remote instance.
+
+
+
pemfile
+
The key to use when executing SSH commands on your remote instance.
+
+
+
branch
+
The git branch of your project that you want to deploy.
+
+
+
ssh-port
+
The SSH port on your remote instance - you usually don't need to change this.
+
+
+
+
Under remotes.${remote_name}.daemon there are some additional settings for the
+Inertia daemon:
+
+
+
+
Parameter
+
Description
+
+
+
+
port
+
The port that the Inertia daemon is using - you can usually leave this as is.
+
+
+
token
+
This is the token used to authenticate against your remote, and will be populated when you initialize the Inertia daemon later.
+
+
+
webhook-secret
+
This is used to verify that incoming webhooks are authenticate - you'll need this later!
+
+
+
Initializing the Inertia Daemon
+
+
inertia ${remote_name} init
+# ... lots of output
+
+
Initializing the Inertia daemon means installing Docker,
+setting up some prerequisites, downloading the Inertia daemon image, and getting
+it up and running. Luckily, this is all done by a single, handy command so you
+don't have to worry about it!
+
+
The Inertia daemon is a small agent that runs on your VPS instance and handles
+all your deployment-related needs, such as responding to commands and listening
+for updates to your repository. You can read more about this in the
+Deployment Management section.
+
+
+
+
+
Configuring Your Repository
+
+
The inertia ${remote_name} init or provision command's output should
+include something like the following:
+
+
GitHub Deploy Key (add here https://www.github.com/<your_repo>/settings/keys/new):
+ssh-rsa <...> # this is important!
+GitHub WebHook URL (add here https://www.github.com/<your_repo>/settings/hooks/new):
+http://myhost.com:4303/webhook # this is important!
+Github WebHook Secret: inertia # this is important!
+
+
The inertia ${remote_name} init or provision command outputs several key
+pieces of information to get your repository set up for continuous deployment:
+
+
+
A deploy key: you need to allow this key read access to your repository. On
+GitHub, this is under your project's "Settings -> Deploy Keys" tab. This will
+allow the Inertia daemon to clone your project.
+
A webhook URL and webhook secret: you'll need to register the Inertia daemon
+for webhook updates to let it automatically deploy your latest changes. On
+GitHub, this is under your project's "Settings -> Webhooks" tab.
+
+
+
+
inertia ${remote_name} up
+
+
+
Deployment Management
+
+
To bring your project online and check its status:
+
+
inertia ${remote_name} up
+inertia ${remote_name} status
+
+
+
To shut down your project:
+
+
inertia ${remote_name} down
+
+
The main commands used to control your deployed project are up, status, and
+down. These commands are associated with the state of your project, not with
+that of the Inertia daemon - inertia ${remote_name} down, for example, will
+not shut down the Inertia daemon.
+
+
Commands like up will provide live output to your terminal. It's pretty normal
+for up to take a while, depending on the performance of your VPS, as it needs
+some time to build your project.
+
Monitoring
inertia ${remote_name} logs
+
+
+
To view the logs of a specific process, get the list of active containers, then
+query for the logs of the container you are interested in:
+
+
inertia ${remote_name} status
+inertia ${remote_name} logs ${container_name}
+
+
TODO: details
+
Secrets Management
+
+
Environment variables are a good way to store secrets:
+
+
inertia ${remote_name} env set${key}${value}
+
+
+
If you use configuration files such as a .env file, you can "send" it to your
+remote - this file will then become accessible by your project:
+
+
inertia ${remote_name} send ${file_name}
+
+
TODO: details
+
Teams
Configuring Users
+
+
The following command will prompt for a password, and add the given user as
+an administrator:
+
+
inertia ${remote_name} user add ${username} --admin
+
+
+
To list existing users:
+
+
inertia ${remote_name} user ls
+
+
+
Access can be revoked for a user by removing them:
+
+
inertia ${remote_name} user rm ${username}
+
+
TODO
+
Logging In
+
+
If you want to log in to a remote you have already configured as a specific
+user, you can run:
+
+
inertia ${remote_name} login ${username}
+
+
TODO
+
+
+
Upgrading
+
+
Install the latest release - for example, on MacOS:
This section details various advanced usage tips. If you can't find what you're
+looking for here, try using the --help flag on relevant commands - Inertia
+will display help text and all the different options available to you.
+
Troubleshooting
+
+
+
+
To view more of the Inertia daemon's logs (the number of entries retrieved
+is capped by default), run:
Inertia is a large and rather complex project, and as such you might encounter
+bugs, either because of Inertia or due to some kind of misconfiguration.
+
+
The Inertia daemon outputs a lot of verbose logs that might help you out. You
+can also make use of the inertia ${remote} status command to output details
+about the state of your deployment. Also pay attention to the output of the
+Inertia CLI when things go awry - it might hint at what happened, and it'll be
+useful context if you decide to open a ticket.
+
+
+
To start an SSH session with your remote, you can use the shortcut:
+
+
inertia ${remote_name} ssh
+
+
If you are more experienced, you can SSH into your remote to investigate. This
+lets you access more advanced Docker commands and whatever else you might need
+to work out what is happening.
+
+
+
2-Factor Authentication
inertia ${remote_name} user totp enable${username}
+inertia ${remote_name} user totp disable ${username}
+
+
2-factor authentication configuration in Inertia is available under the
+inertia ${remote_name} user totp commands.
+
+
TOTP stands for "time-based one-time password". Enabling TOTP on an account
+means that whenever a user logs in using that account, they must also verify
+their identity using a separate authenticator app, which provides a secondary
+factor of authentication - hence why it is called "2-factor authentication".
+
+
There are a wide range of authenticator apps out there, for example:
To log in as a totp-enabled user, you'll have to provide your TOTP or backup
+code as a flag:
+
+
inertia ${remote_name} user login ${username} --totp ${code}
+
+
When you enable TOTP on an account, Inertia will output a QR code that you can
+scan using your authenticator app, as well as a list of backup codes you should
+keep somewhere safe. When you log in using a TOTP-enabled account, you'll need
+to provide the TOTP generated by your authenticator app to log in, or one of the
+backup codes.
+
Resource Management
+
+
To clear out unused Docker images and containers:
+
+
inertia ${remote_name} prune
+
+
+
You can also interact with Docker directly over SSH:
+
+
inertia ${remote_name} ssh
+root@remote:~$ docker container ls -a
+
+
Inertia does its best to manage resources on its own, but sometimes spare
+containers and images start gathering and you might find your remote starting
+to run out of storage (especially if it is a free/budget instance with low
+storage).
+
+
Inertia offers a few ways of managing resources, either through commands like
+prune or directly over SSH.
+
+
+
Generating API Keys
inertia ${remote_name} token
+
+
If you want to develop integrations with Inertia, you'll probably want a
+non-expiring API token, which you can generate using Inertia if you have SSH
+access to your remote. Be careful not to lose these tokens.
To use these tokens, you can place them in your inertia.toml under token, or
+use them in requests to the Inertia API by placing them as a Bearer token in
+your request header under Authorization.
+
Inertia Release Streams
+
The version of Inertia you are using can be seen in Inertia's inertia.toml
+configuration file, or by running inertia --version. The version in
+inertia.toml is used to determine what version of the Inertia daemon to use
+when you run inertia ${remote_name} init.
+
+
+
To switch over to the latest build and upgrade your remote:
+
+
inertia config set version "latest"
+inertia ${remote_name} upgrade
+
+
You can manually change the daemon version used by editing the Inertia
+configuration file. If you are building from source, you can also check out the
+desired version and run make inertia-tagged or make RELEASE=$STREAM.
+Inertia daemon releases are tagged as follows:
canary denotes experimental builds used for testing and development - do not use this.
+
+
+
You can see the list of available tags on
+Docker Hub.
+
Custom SSL Certificate
+
By default, the Inertia daemon generates a self-signed SSL certificate for its
+API. This means that Inertia, by default, doesn't verify SSL communications,
+and you'll have to do things like disable SSL verification in your repository
+for webhooks.
+
inertia ${remote_name} --verify-ssl status
+
+
If you provide your own SSL certificate, you can enable SSL verification in
+Inertia using the --verify-ssl flag, and enable SSL verification in your
+repository's webhook deliveries as well.
+
+
Just place your SSL certificate and key on your remote in ~/.inertia/ssl as
+daemon.cert and daemon.key respectively, and the Inertia daemon will use
+them automatically.
[![Deployed with Inertia](https://img.shields.io/badge/deploying%20with-inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
+
+
Add a cool Inertia badge to your README if you use Inertia!
+
+
+
Contributing
+
Any contribution (pull requests, feedback, bug reports, ideas, etc.) is welcome!
+
+
You can report issues with documentation, bugs, or anything via our
+issue tracker.
+
+
For development, please see our
+contribution guide
+for contribution guidelines as well as a detailed guide to help you get started
+with Inertia's codebase.