Create a component
An Architect component is comprised of one or more services that live and die together. The services
are tied together via the architect.yml
file, and one Architect component may
depend on another by specifying it in the dependencies
block. This guide uses the
React starter project to help you learn about defining
an Architect component.
Prerequisites
The following prerequisites are required for a smooth introduction to Architect:
- Some familiarity with running applications using Docker (or any other similar container engine)
- Docker installed and running
- Architect CLI installed
You don’t need to know how to use Kubernetes or how to deploy an application into a cloud environment - Architect handles that for you.
Get Started
A component includes all the services and dependencies that comprise your application. Creating a new component that can be run in the Architect cloud as well as any external clusters you add involves the following steps:
- 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
Clone the React starter project
You can clone the React starter project yourself or use the architect init
command to let Architect clone
it for you.
Use the architect init
command
Run the architect init
command and select React
from the drop-down list.
% architect init
? What is the name of your project? my-starter-project
? Please select a framework/language for your project
Nodejs
Nuxt
❯ React
Ruby-on-Rails
Springboot
ASP.NET Core
Django
(Move up and down to reveal more choices)
...
######################################
##### Let's set up your project! #####
######################################
Creating project directory... ✓
Pulling down GitHub repository... ✓ react
Successfully created project my-starter-project.
Your project is ready to be deployed by Architect!
To deploy locally, run:
architect dev my-starter-project/architect.yml
Use git clone
You’ll need git
installed to clone the starter project manually.
If you don’t have git
installed, use the architect init
command.
To clone the starter project yourself, run the
following command:
git clone https://github.com/architect-templates/react.git
Open the architect.yml
file
Now that you have the React starter project cloned locally open the architect.yml
file in your favorite editor
and follow along.
Define a Component
Let’s take a look at the architect.yml
file.
Component metadata
The top of the architect.yml
file defines some metadata for the component.
name: react
description: An Architect Starter Project using React.
homepage: https://github.com/architect-templates/react
keywords:
- react
- express
- javascript
Once the component is registered, the name
and description
will be visible on the Components page in the Architect UI. The name
property is also how components specify other components as dependencies.
Secrets
The next block defines secrets that will be available to the component at runtime.
secrets:
db_user:
description: Root user to assign to the component's DB
default: architect
db_pass:
description: Root password to assign to the component's DB
default: secret
db_name:
description: Name of the DB the component will store content in
default: api-db
db_port:
description: Port for the db
default: 5432
api_port:
description: Port for api
default: 8080
Services
The services
section defines the services that comprise this component. In this case, we have the following services:
app
- the React app itselfapi-db
- the database used by the backend APIapi
- the backend API
You must specify a unique key for each service, and the key is used to reference the service in other sections of
the architect.yml
.
services:
app:
build:
context: ./
args:
NODE_ENV: production
...
Build
You’ll notice that the app
service contains a build
section. This section tells Architect how
to build an image for this service using Docker. The context
property indicates which directory to build
from, relative to the architect.yml
file. The path is .
in this case since the architect.yml
file is in the
same directory as the application code. By default,
Architect expects a Dockerfile named Dockerfile
in the location provided in the context
.
This section sets the NODE_ENV
environment variable to production
. This variable is used in the Dockerfile
so that the image can be built differently for production vs. building for local development.
Other configuration options for the build
section
can be found here.
build:
context: ./
args:
NODE_ENV: production
Interfaces
The interfaces
section contains a set of named interfaces that the service
listens for requests on. The app
service defines an interface named main
that listens for
requests on port 8080
over http.
interfaces:
main:
port: 8080
The interfaces
defined in the services section are for internal communication only and do not
expose the service publicly. For a service to be reached by outside
users or applications, you must
define ingress rules.
The protocol, port, hostname, and more are also available as configuration
options for the interfaces
section.
An in-depth breakdown of the available configuration options for a service can be found here.
Ingress
To expose the app
service to the outside world, we define an ingress on the
interface we just created. This defines the subdomain that will be used to
expose the interface externally.
interfaces:
main:
port: 8080
ingress:
subdomain: app
Environment
The environment
section defines environment variables that the service can access at runtime. You’ll notice that the
app
service defines a REACT_APP_API_ADDR
variable that uses service discovery to
extrapolate the value.
environment:
PORT: 8080
REACT_APP_API_ADDR: ${{ services.api.interfaces.http.ingress.url }}
Liveness probe
The liveness_probe
section defines the command
to run to check whether a service is healthy. In this case,
the command is run every 30 seconds, and the service is restarted after the command fails three times.
liveness_probe:
command: curl --fail 0.0.0.0:8080
interval: 30s
failure_threshold: 3
Debug
The debug
section indicates how the service should be built for local development. This section comes into play when
you run the component locally using the architect dev
command.
debug:
command: npm run dev
build:
args:
NODE_ENV: development
volumes:
src:
mount_path: /usr/src/app/src
host_path: ./src
We set the NODE_ENV
environment variable to development
so that Docker knows to build the image for local development.
The Dockerfile for this component uses this variable to determine whether to run npm run build
when building the image
for this component.
RUN if [ "$NODE_ENV" = "development" ] ; then echo "Debug mode enabled. Skipping build." ; else npm run build ; fi
The volumes
section mounts the local source code directory as a volume in the container to allow for hot reloading
during development.
volumes:
src:
mount_path: /usr/src/app/src
host_path: ./src
Image
The api-db
and api
services each define an image
rather than specifying a build
context.
api-db:
image: postgres:12
...
api:
image: devmandy/starter-project-api:v1
The api-db
service uses version 12
of the official
postgres
image. The api
service uses a custom Docker image for an API. This image was built for frontend
starter projects to simplify the learning experience. For your services, you will use
dependencies to consume a separate API.
Run locally
Once you have defined a component by creating an architect.yml
file, you can test it by running the component locally.
To run the component locally, run the following command from the top-level directory:
architect dev
Once the containers are running, you can see your frontend at https://app.localhost.architect.sh.
Notice that the subdomain app
comes from our defined ingress subdomain.
Register a component
You must register a component before deploying it to the Architect cloud or an external cluster. You’ll start by logging in.
$ architect login
If you have not registered yet, create a free account. Once you’ve successfully logged in, you can now register the component by running the following command from the top-level directory:
$ architect register
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.