Hello World!

No introduction is complete without a classic hello world program. And what better way to say hi other than a simple "hello world" project. Let's dive in and create the simplest possible infrastructure in Octo - a static website!

Create a new App

Octo supports Templates - pre-configured and pre-tested collection of modules to help you get started fast. You can start and customize one of the many templates provided by Octo, or create a new one from scratch.

Templates can be written in YAML or TypeScript. In this tutorial we are work with YAML.

# Create a new directory "test-app" in current directory,
# and set up a new Octo app using the "aws-s3-website" template.
npx @quadnix/octo-build create-app -t aws-s3-website -n test-app -p .

# Enter the "test-app" directory.
cd test-app

# Initialize the Octo app.
npm install

This should create a directory structure like this: Octo App Structure

Customizing the App

You will first need to modify below files with your custom values before you can run the app.

Definition File

octo.yaml

env:
  - key: AWS_ACCOUNT_ID
    kind: string
    value: "123456789123"
  - key: AWS_S3_WEBSITE_BUCKET_NAME
    kind: string
    value: my-website-unique-bucket

Running the App

# First create a lock.
node_modules/.bin/octo state lock -d octo.yaml

# Then copy the lock output, a random unique string, and run the app with the lock ID.
OCTO_APP_LOCK_ID=<lock_id> node_modules/.bin/octo run -d octo.yaml

# Lastly, unlock the app.
node_modules/.bin/octo state unlock <lock_id> -d octo.yaml

octo.yaml has the module definitions for creating the S3 bucket. By running the app, you ran all the modules which created the desired infrastructure as per their instructions. The log outputs and HTML reports show this information in more detail.

info

In your package.json, the @quadnix/octo-build package exposes the octo executable. You can either add node_modules/.bin to your PATH environment variable to directly call the octo executable, or you can call this executable with the full path node_modules/.bin/octo. Throughout our examples we will use the full path to avoid any confusion.

Testing the App

Modify and visit these URLs to ensure the website is up and running.

http://<my-bucket-name>.s3-website-us-east-1.amazonaws.com/index.html
http://<my-bucket-name>.s3-website-us-east-1.amazonaws.com/error.html

Need help ?

If the script didn't work out, please open an issue using links at the bottom of this page.

What just happened?

You created your first infrastructure using Octo! You ran some pre-built modules imported in octo.yaml that creates and sets up a static website in AWS S3.

Octo ran these modules, and saved the state of all models and resources that got created in the .octo directory! These represent the state of your infrastructure. Do not modify or delete these files. If you wish, inspect the file and get familiar with its structure.

models.json
resources.json
<my-bucket-name>-manifest.json

tip

If you run the app again, it would use the state files to detect that the website already exists, and won't do anything. If you were to edit the HTML files and re-run the app, Octo would detect these changes based on the state files, and will re-upload the changed files to the S3 bucket.

Hopefully, this example demonstrated you the benefits of Octo! You were able to accomplish your infrastructure needs using Octo's abstracted components, without having the need to implement the low level resources. You can inspect the state files and logs to understand the cloud resources created by Octo.

HTML Reports

After each run, Octo generates an HTML report that shows the changes made to the infrastructure. You should notice a new HTML file in your root directory. You can view the HTML report in any web browser - simply drag and drop the HTML file into the browser, or double-click the HTML file.

This report gives you an overview of the changes made to the infrastructure. You will often find this report beneficial to review the transaction after every run to ensure changes were applied as expected.

Cleaning Up (Optional)

To clean up all the resources created thus far, modify the octo.yaml file. Comment out all modules except the app and account modules. The app and account modules load AWS credentials to call AWS APIs, hence they should remain intact.

By deleting the s3-website-service-module module below, you are deleting the s3-website resources created by this module.

modules:
  - moduleId: app-module
    moduleClass: SimpleAppModule
    moduleInputs:
      name: aws-s3-website

  - moduleId: account-module
    moduleClass: AwsIniAccountModule
    moduleInputs:
      accountId: "${env.AWS_ACCOUNT_ID}"
      app: "${{app-module.model.app}}"

#  - moduleId: s3-website-service-module
#    moduleClass: AwsS3StaticWebsiteServiceModule
#    moduleInputs:
#      account: "${{account-module.model.account}}"
#      awsRegionId: us-east-1
#      bucketName: "${env.AWS_S3_WEBSITE_BUCKET_NAME}"
#      directoryPath: website

Then, simply re-run your app again.

# First create a lock.
node_modules/.bin/octo state lock -d octo.yaml

# Then copy the lock output, a random unique string, and run the app with the lock ID.
OCTO_APP_LOCK_ID=<lock_id> node_modules/.bin/octo run -d octo.yaml

# Lastly, unlock the app.
node_modules/.bin/octo state unlock <lock_id> -d octo.yaml

Now you can just delete the Octo directory and all the code in it.

rm -Rf test-app

Summary

In this comprehensive guide, we hosted a simple website with just a few lines of code. In later sections, we will delve deeper into every detail of how this all worked and explore further possibilities with Octo.