Installation
Requirements
Octo is based on TypeScript, allowing you to use it as either a Node.js project or a TypeScript project. Before you get started, here are a few things you need to ensure are installed and configured properly.
| Program | Description | Version |
|---|---|---|
| Node.js | Previous versions may also work, although we do not test them frequently. To install node, there are several help articles available online, but we really love using nvm. | >= 22.x (Supported) |
| aws-cli | Assuming you want to build the infrastructure on AWS, you will need to set up aws credentials. You can either set up aws-cli using aws official docs, or use our aws setup guide for alternatives such as using inline credentials. | >= 2.x (Recommended) |
Disclaimers
The docs only provides syntax for TypeScript, but Octo projects can be written in pure Node.js. If you decide to use Node.js, it is up to you to translate all instructions accordingly.
Octo exclusively supports ESM modules, requiring "type": "module" in package.json.
In this blog post, we explore using Octo with CJS modules.
Please translate all instructions accordingly.
Note that we don't test Octo with CJS modules regularly, so if you encounter issues, please let us know.
Naming Conventions
Before we dive into creating new infrastructure, let's set some important expectations.
Naming things is one of the trickiest parts of any project, especially in infrastructure. Names are frequently reused and directly impact actual cloud resources. Once established, changing these names can become incredibly difficult, often requiring you to re-create large portions of your infrastructure.
Fortunately, Octo handles much of the resource naming for you, but it still requires some initial inputs. Please be cautious with these inputs, as any changes to them later on could introduce breaking changes to your existing infrastructure.
- Repositories/Projects written in Octo are called Apps.
- A single App is a monorepo, and contains all the infrastructure for this app. E.g. if you app requires multiple servers, like a backend-service, and a payment-service, definitions of each will be inside this same repository.
- Having a mental model of your final infrastructure usually helps in naming. E.g.
- Number of regions or shards, and their names.
- Types of environments - qa, staging, prod, etc.
- A separate account for environment, vs a single account.
Much of these nuances will get more apparent as you experiment with Octo. So let's get started!
Summary
In this article, we explored pre-requisites and set up instructions for Octo on your local machine. Next, we will create a "hello world" project to see a live example.