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 infrastructure 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.

# 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

Customizing the App

You will first need to modify below files before you can run the app.

Environment File

.env

# Fix me: AWS account ID.
AWS_ACCOUNT_ID=123456789123

# Fix me: S3 bucket name.
AWS_S3_WEBSITE_BUCKET_NAME=my-website-unique-bucket

Running the App

# Compile the app.
npm run build

# Run the app.
npm start

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 module-definitions.ts 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 as expected.

Cleaning Up (Optional)

To clean up all the resources created thus far, modify the module-definitions.ts. Comment out all modules except the app and account modules. The app and account modules load AWS credentials to call AWS APIs, hence they remain uncommented.

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

private init(): void {
  this.add(SimpleAppModule, 'app-module', { name: 'aws-s3-website' });

  this.add(AwsIniAccountModule, 'account-module', {
    accountId: config.AWS_ACCOUNT_ID,
    app: stub<App>('${{app-module.model.app}}'),
  });

  // *************************
  // Comment out below module.
  // *************************

  // this.add(AwsS3StaticWebsiteServiceModule, 's3-website-service-module', {
  //   account: stub<Account>('${{account-module.model.account}}'),
  //   awsRegionId: 'us-east-1',
  //   bucketName: config.AWS_S3_WEBSITE_BUCKET_NAME,
  //   directoryPath: websiteSourcePath,
  // });
}

Then, simply re-build and run your app again.

npm run build
npm start

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.