Torus Host Docs

Intro

Torus Host is a fully open source deployment system for static (jam stack) websites that provides complete automation of the entire deployment process including domain operations, infrastructure provisioning and content delivery. It features an easy to use multi command line interface and 3 node js SDKs.

With Torus you have a seamless deployment experience of an all-in-one service like Netlify, while still maintaining full control of your entire stack and deployment process. You are free to choose what resources you want to use, from which providers, and to customize them as you like.

Torus works works with any static website and most popular front end frameworks such as React, Gatsby js, Vue, Svelte, Flutter, Ember and others. You can publish HTML/CSS/JS directly from your local directory or add continuous integration to your projects to automate the build process for your front end apps.

Torus currently supports AWS and Godaddy but more integrations with other cloud providers and domain registrars are coming soon.

mission

  1. Enable design firms and freelancers to offer enterprise-grade hosting services without the need for devops experts or the extra $$$.
  2. Give front-end developers a seamless deployment experience without sacrificing control.
  3. Make it easy for developers/software companies to offer hosting within their applications. (SSG’s, CMS’s, domain registrars, etc)

Getting Started

In this example you will deploy a static website with a custom domain and HTTPS to an enterprise-grade edge network (AWS Cloudfront).

  • When using Torus Tools you are using your own AWS account from your own machine. Any charges incurred by your websites will be billed directly from AWS to your AWS account.
  • Torus Tools does NOT have any access whatsoever to your AWS account/bill or API keys.

pre requisistes:

  • An AWS account
  • Node. js v.12+ and NPM
  • Have a custom domain
  • The latest version of the Torus CLI npm i -g @torus-tools/cli

Quick Start:

Step 1: One time global provider configuration torus init -g -p=awsStep 2: One command deploy for your sitetorus stack create prod -d=yoursite.com -r=godaddy(Make sure to be in the root folder of your project. If you are using a domain provider other than Goddady, add other to the registrar flag. The nameservers will be displayed in the CLI, as the resources are being created, so you can add them to your domain provider manually)You are all done!

Just be a little patient while the security certificate and resources are being created in AWS.

Remember you can always run torus help if you need more help.

Pre defined Templates:

For an easier development workflow we have defined some setups that include Dev, Test and Prod (production). You can customize these by additionally providing flags.

dev → test → prod
  1. Dev: public S3 bucket
  2. Test: public S3 root bucket, www reroute bucket and a route53 hosted zone.
  3. Prod: public S3 root bucket, www reroute bucket, route53 hosted zone, cloudfront distribution, ACM certificate

How it works

Overview

Torus Hosting is made up of a multi command line interface and 3 SDKs; Stack, Domains and Content. The SDKs are meant to standardize operations for domains, DNS, other infrastructure components and content across different cloud/domian providers. On the other hand, The CLI facilitates the user’s interaction with the SDKs, providing a seamless developer experience with unmatched flexibility.

Stack command execution order

The torus stack method and the respective stack command in the CLI help you deploy the required infrastructure pieces for a modern static site inside a single cloudformation JSON template. Depending on the options provided within the config object the command will generate different pieces of infrastructure. If you have an existing stack, any options provided will update your current stack. If you have existing resources for the given websites domain that live outside of your cloudformation stack, they will be imported into the stack.

execution order of the torus stack command

You are always free to customize the generated cloudformation template or its resources individually in any way you want using the AWS console/CLIs/SDKs and/or the torus stack SDK/CLI command. You can also push the arjan_config to github and enable other team-members (with permission) to collaborate on the stack. Additionally the stack command also facilitates registrar, DNS, and content operations in a specific order.

Stack Creation

For a production stack, the creation of infrastructure happens in two parts. First the stack creates the s3 bucket (storage), bucket policy, www reroute bucket and optionally the route53 hosted zone (DNS). Then the stack is updated adding an ACM certificate and cloudfront distribution (CDN).

Nameserver transfers

Torus will automatically transfer nameservers for domains registered in godaddy.com. If you are using another domain registrar the CLI will output the corresponding nameservers and wait for you to transfer them. Please beware that some registrars might take longer than others to complete the nameserver transfer. With godaddy, as well as namecheap the transfer is usually pretty quick but this may vary. Its always a good idea to check with a free DNS tool like mxtoolbox.com if your nameservers have propagatyed correctly.

Content Upload

By default, the torus stack command will also upload all the files in your current working into the s3 bucket deployed. The operation will ingore any sensitive files that are in your gitignore. additionally, if you have other files that you do want to commit to git, but you dont want to upload into your site you can create an additional .torusignore file. Typical files/dirs that you may add into torusignore include .git, .gitignore, .github, package.json, etc. You can auto-generate this file with these defaults by running torus init inside your project.

Project structure

  |-- .torusignore
  |-- torus
    |--config.json
    |--reosurces.json
    |--template.json

CLI Commands

The Arjan CLI lets you easily run and overwrite local configurations with flags/arguments. This make it really flexible and easy to configure and provides a flexible developer experience. Generally every command in the CLI performs the following actions:

  1. read global env variables
  2. set process env variables
  3. create/read the torus/config.json file
  4. read the .env file
  5. execute the command

Torus help

display help for torus

USAGE
  $ torus help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
--all see all commands in CLI

Torus Init

Configure torus globally in your machine, or on a per-project basis

USAGE
  $ torus init

OPTIONS
-d, --domain=domain
      The valid desired/existing domain of your site i.e. yoursite.com

-g, --global
      Create a global torus configuration file. The command will guide you through the steps to generate the required API 
      keys for each of your desired providers, set up your global environment variables and your deisred default settings.

-p, --providers=aws|godaddy
      Desired cloud/domain providers to be used with torus. You must have an existing account in all of the providers you 
      choose.

-r, --region=us-east-2|us-east-1|us-west-1|us-west-2|af-south-1|ap-east-1|ap-south-1|ap-northeast-2|ap-southeast-1|ap-sout
  heast-2|ap-northeast-1|ca-central-1|cn-north-1|cn-northwest-1|eu-central-1|eu-west-1|eu-west-2|eu-west-3|eu-north-1|me
-south-1|sa-east-1|us-gov-east-1|us-gov-west-1
      [default: us-east-1] Desired AWS region

-u, --user=user
      [default: torus_admin] Desired name for the AWS IAM user

DESCRIPTION
  ...
  The init command helps you configure torus in your site/project. Providing the -g (--global) flag helps you configure 
  torus globally (for all of your projects). When using the torus CLI, you can always overwrite global settings by 
  including a project config file. You can also overwrite global environment variables by including a .env file. If you 
  are using the init command without the -g flag make sure to run it from the root of your project.

Torus Stack

All-in-one deployment solution for static sites in AWS. Creates the required infrastructure, carries out the necessary domain/dns operations and uploads your website content.

USAGE
  $ torus stack ACTION [SETUP]

ARGUMENTS
  ACTION  (create|update|import|delete|pull|push) choose an action to perform. you can create, update, import your stack
          or upload files to your bucket.

  SETUP   (dev|test|prod|custom) [default: dev] setup for the site - dev, test, production or custom

OPTIONS
-b, --bucket=aws|true Enables a cloud storage bucket to be used as the websites origin. You can
                                          provide this flag without the =string to use aws s3.

-c, --cdn=aws|true Add a CDN to your site. CDNs enable faster website load times by caching your
                                          content around the globe (the edge). You can provide this flag without the
                                          =string to use aws Cloudfront.

-d, --domain=domain The domain of your site i.e. yoursite.com

-e, --error=error name of the error document. Default is error.html

-i, --index=index name of the index document. Default is index.html

-o, --overwrite By default, torus always reads your template in the cloud and only adds
                                          changes (updated resources or additional resources). If you want to eliminate
                                          the resources that arent prvoided in the CLI flags you can add this flag.

-p, --publish Publish the sites content

-r, --registrar=aws|godaddy|other|true The current domain name registrar of your sites domain. Using AWS or godaddy
                                          enables automatic namserver updates if the DNS provider is different to the
                                          registrar. Selecting other will require manual nameserver updates. true
                                          evaluates to other.

-s, --ssl=aws|true Enables https by creating and validating an SSL certificate for your site. You
                                          can provide this flag without the =string to use aws certificate manager.

-w, --www=true creates a www reroute bucket.

--dns=aws|godaddy|other|true Desired DNS provider for your site. The aws option adds a route53 hosted zone
                                          to your stack. You can provide this flag without the =string to use aws.

DESCRIPTION
  ...
  Deploy static sites to the AWS Cloud using Cloudformation templates.

Torus Content

List/download/upload/delete all of your content (or the specified files).

USAGE
  $ torus content ACTION [FILES]

ARGUMENTS
  ACTION  (list|download|upload|delete) given action to carry out with the content of your site

  FILES   local paths or object keys of the files/directories you want to upload/download to/from your bucket. For
          example suppose theres a directory img inside the cwd the path of image1.jpg would be img/image1.jpg. For
          local files the root is the current working directory unless specifiecd otherwise with the -i flag. By
          default, if no paths are provided all files/dirs in the root will be used.

OPTIONS
-a, --all Upload all files. By default only updated files are uploaded. -d, --domain=domain Domain of your site (i.e. yoursite.com). -i, --input=input Path of the root directory of your project (if different to the current working driectory). -o, --output=output [default: ./] Path to save downloaded content into. Default is the current working directory. -r, --reset Reset the cache in all edge locations for the given files. -s, --sort Sorts listed files by last modified date.

DESCRIPTION
  ...
  By default only modified files are uploaded; to upload all files provide the --all flag. To automatically update cache 
  in cloudfront for the given files add the --reset flag.

Advanced Configuration

The global configuration file sotred in ~/.aws/config holds the standard environment variables that the user intends to use on most of their projects. the global config file uses a simple toml format and it includes both the API keys/env variables for each cloud/domain provider as well as the providers configuration that sets which provider should be used for which resource. The codeblock bellow shows a sample gloabl config file for a user that usually deploys sites with a Godaddy domain, AWS Bucket, AWS route53 DNS, AWS Cloudfront CDN, and AWS ACM Certificate. Notice that for the aws provider we dont have to provide API keys as we can reference the AWS config in ~/.aws/credentials. If you dont have a global AWS config you can also provide the API keys directly as access_key_id and secret_access_key.

[aws]
region=us-east-1
profile=default

[godaddy]
api_key=fe98wkf287e927198dnj87589hjspi
secret_key=iufyewuiyf8746r98370

[providers]
domain=godaddy
bucket=aws
cdn=aws
dns=aws
https=aws

The diagram bellow represents the flow of configuration variables.

Torus_config JSON file

every project will have a torus config file that will contain the default providers for that project. You may modify this config file manually at any time or on a per-instance basis by providing CLI flags

const config = {
  index:"index.html",
  error:"error.html",
  last_deployment:"",
  providers: {
    registrar: 'godaddy',
    bucket: 'aws',
    cdn: 'aws',
    dns: 'aws',
    ssl: 'aws'
  }
}

Contributing

Anyone can contribute to Torus. All you have to do is fork the repository and submit a pull request. If you are interested in continually improving Torus and helping us tackle our weekly sprints, contact us and we will let you into our organization. This way you can edit and prioritize issues in the project board and you can assign yourself to issues that you plan on completing.

If you are making your first contribution to Torus we recommend grabbing an issue from the backlog that isn't at the top. This way you wont be working on an issue that someone else from the core team will work on, otherwise please contact us through slack.