Architect.io Docs

Creating a Component

This tutorial covers how you can quickly get started using Architect.

Prerequisites

The following prerequisites are required for a smooth introduction to Architect:

  • An application that can be run in a container
    • If you're just curious what Architect has to offer, you can clone one of our Templates and use that to get started.
  • Some familiarity with running applications using Docker (or any other similar container engine)

It isn't necessary to know how to use Kubernetes or how to deploy an application into a cloud environment - Architect handles that for you.

Getting Started

Creating a new component on the Architect platform involves:

  • Writing an architect.yml file
  • Running and testing the component locally with architect dev
  • Using the architect register command to register this component with your Architect account.

If you don't yet have the Architect CLI installed, see our instructions on how to do that.

You can create your own component with a pre-existing app you've built, or clone our React Template to follow along.

Suppose we are working within a repository for a simple React app with the following file structure:

src/
index.js
Dockerfile
package.json
package-lock.json

We can create an architect.yml file for this repo so that we can easily run our application locally and on the cloud with Architect.

Defining a Component

Component Metadata

First, we can add some metadata to the top of our architect.yml to help identify our component.

name: react
description: A react frontend component

The name and description will be visible on the Components page once the component is registered.

Defining a Service

Next, we can add a services section that defines one or more services that are part of this component. Each service is defined by a top-level unique key that you choose, and can be referenced in other sections of the architect.yml. Our service will be called my-app in this example.

name: react
description: A react frontend component
services:
my-app:
build:
context: .
interfaces:
main: 8080

The build section

build:
context: .

The build section specifies details necessary for Architect to build an image for this service via Docker. context tells Architect what directory to build from, relative to the architect.yml. In this case, architect.yml is in the same directory as our application, so we specify the path .. By default, Architect expects a dockerfile named Dockerfile at the provided context to build the image.

Other configuration options for the build section can be found here.

The interfaces section

interfaces:
main: 8080

The interfaces section contains a set of named interfaces that the service listens for requests on. main: 8080 is a shorthand way to define an interface named main that listens for requests on port 8080 over http.

Importantly, this interfaces definition within the services section does not expose the service publicly. In order for a service to be reached by outside users or applications, see Defining an Interface.

The protocol, port, hostname, and more are also available as configuration options for the interfaces section. Details can be found here.

An in-depth breakdown of the available configuration options for a service can be found here.

Defining an Interface

In order to reach our service from a browser, we must create a named interface with a URL we can use to connect to our service.

interfaces:
my-interface:
url: ${{ services.my-app.interfaces.main.url }}
ingress:
subdomain: test

Just like services, each top-level interface key can be any unique key that you want to use. Our interface will be named my-interface for this example.

url: ${{ services.my-app.interfaces.main.url }} specifies the address this interface brokers traffic to. In this case, it is dynamic - the URL is a computed value from our service my-app's interface named main.

Finally,

ingress:
subdomain: test

defines the subdomain that will be used to expose the interface externally.

The final version of the architect.yml should look like:

name: react
description: A react frontend component
services:
my-app:
build:
context: .
interfaces:
main: 8080
interfaces:
my-interface:
url: ${{ services.my-app.interfaces.main.url }}
ingress:
subdomain: test

Running Locally

Our architect.yml currently defines a very basic service that only has a static frontend and an interface that allows us to connect to it. We will fix that shortly, but we already have enough to create a component.

In order to test that the architect.yml is set up correctly, we can run:

$ architect dev architect.yml

After the image is built, you will be able to see your frontend at test.arc.localhost. Notice that the subdomain test is coming from our defined ingress subdomain.

Registering a Component to be deployed on the Cloud

In order to deploy this service to the Architect Cloud, we can run:

$ architect login

If you have not registered yet, create an account. Once you've successfully logged in, you can now register the component by running:

$ architect register architect.yml

Now, when you view the Components page on https://cloud.architect.io, you will see a component named react that was just registered! Try deploying the app in the cloud by clicking the "Deploy" button on the component card.

No results found for query ""