Introduction
Architect centers around the needs of developers, enabling them to create deployment pipelines without needing to know about the operational details of building and maintaining modern DevOps infrastructure.
Developers love Architect because it emulates tools they use and love already, like NPM, to describe their application architecture and declare its dependencies. DevOps engineers love Architect because our automation makes deployments flexible, dynamic, and secure so that DevOps can focus on other, value-generating initiatives to support developers rather than constraining them unnecessarily.
How do we do this?
- We use Docker to make deployments portable
- We use a config file (
architect.yml
) to describe your app’s structure and dependencies - We provide a single command to deploy locally, to deploy to a preview environment, or to deploy to production
First steps
Install the CLI
We built Architect for developers, and our feature-rich CLI provides the best developer experience. Before you do anything else, install Docker and NPM if you haven’t already, and make sure Docker is running.
Then install the CLI via NPM:
npm install -g @architect-io/cli
Alternatively, you can download the binary for your system architecture from
Github.
Just download the appropriate bundle, extract it, and link the included bin
folder to your user home directory.
Try a Starter Project
To help you get started using Architect, we’ve provided several
starter projects that use different languages and
frameworks. While Architect is
language-agnostic, we know developers have preferences, and we aim to give each developer a learning context they are
comfortable with. Each starter project implements a simple application and defines it as an Architect Component using the
architect.yml
config file. You can clone the starter project repository to your local machine or use the architect init
command.
Run architect init
The architect init
presents you with all the starter projects available and clones the one you select to your local machine.
%architect init
? What is the name of your project? my-starter-project
? Please select a framework/language for your project React
######################################
##### 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
The repo for the selected starter project should now reside where you ran the architect init
command.
Run locally
One of the key benefits of using Architect is the ability to run your application on your local machine seamlessly.
To run the starter project you just cloned, copy the architect dev
command displayed when the architect init
command
completes, and run it from the same location where you ran the architect init
command. The architect dev
command runs your
application and all its dependencies in your local Docker environment. You will see output similar to the following:
architect dev my-starter-project/architect.yml
Building containers... done
Once the containers are running, they will be accessible via the following URLs:
https://app.localhost.architect.sh:443/ => react
[7:45:17 PM] Starting compilation in watch mode...
# begin log stream...
You’ll notice in the output above that one or more URLs are provided, depending on your starter project.
For example, starter projects with a frontend will be accessible at https://app.localhost.architect.sh:443/
as
soon as the startup completes.
When you run the command above, Architect reads the architect.yml
file in the repo and transforms it into
a fully enriched docker-compose.yml
file. The application described in this file is run automatically in your local
Docker environment. As shown in the example above, the output from this command provides the URLs where
the services that comprise this component can be accessed. Depending on which starter project you use, your output
may differ slightly. If your starter project contains a frontend service, it will automatically launch in a web browser
once the application is started.
Check out the architect.yml file
The architect.yml
file describes the different services that comprise your application. This is where you’ll define
the interfaces and ingress rules that allow access to your application as well as secrets and dependencies.
This is the architect.yml
file for the react
starter project. Yours will vary slightly depending on the project you
are working with.
For users of Visual Studio Code, check out the Architect extension!
name: react
description: |
An Architect Starter Project using React.
homepage: https://github.com/architect-templates/react
keywords:
- react
- express
- javascript
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
# Below are the configured services for the React component.
# For more info - https://docs.architect.io/components/services/
services:
app:
# Build context is the location of your application relative to the
# architect.yml file
build:
context: ./
args:
NODE_ENV: production
# Main interface port used to help define the url in the `interfaces` block
interfaces:
main:
port: 8080
# Ingresses are used to expose the application to the API gateway,
# allowing other services and dependencies to connect to it.
# For more info - https://docs.architect.io/components/ingress-rules/
ingress:
subdomain: app
environment:
PORT: 8080
REACT_APP_API_ADDR: ${{ services.api.interfaces.http.ingress.url }}
# The entrypoint is used here to import environment variables to the client-side
# app in production
entrypoint: /usr/src/app/bin/entrypoint.sh
command: npm run start
# The liveness_probe makes sure the application is healthy - if not, it will
# re-start the application
liveness_probe:
command: curl --fail 0.0.0.0:8080
interval: 30s
failure_threshold: 3
# The debug block is used to enable hot-reloading to make real-time changes to an
# application while running `architect dev`. For more info, see -
# https://docs.architect.io/components/local-configuration/#hot-reloading
debug:
command: npm run dev
build:
args:
NODE_ENV: development
volumes:
src:
# The `WORKDIR` defined in the Dockerfile (/usr/src/app) + name of source code
# directory (/src)
mount_path: /usr/src/app/src
# Path to source code relative to the architect.yml file (/src)
host_path: ./src
api-db:
image: postgres:12
interfaces:
database:
port: ${{ secrets.db_port }}
protocol: postgresql
environment:
POSTGRES_USER: ${{ secrets.db_user }}
POSTGRES_PASSWORD: ${{ secrets.db_pass }}
POSTGRES_DB: ${{ secrets.db_name }}
api:
image: devmandy/starter-project-api:v1
interfaces:
http:
port: ${{ secrets.api_port }}
ingress:
subdomain: api
environment:
DB_ADDR: ${{ services.api-db.interfaces.database.url }}/${{ secrets.db_name }}
DB_USER: ${{ secrets.db_user }}
DB_PASS: ${{ secrets.db_pass }}
PORT: ${{ secrets.api_port }}
Make your own changes
As you may have noticed, there is a debug
block in the architect.yml
file
that enables hot-reloading for each service within the component. That means you can make changes to
the source code, which will automatically apply to the environment. This allows you to quickly
iterate and see your changes without restarting the application stack.
Create a free Architect account
Now that you’ve successfully run and edited a component locally, it’s time to learn how to register the component and deploy it to a cloud environment. Before you can do that, however, you need to sign up for Architect and create a free account that will house your components and environments.
Login to Architect
After you’ve signed up, you need to login via the CLI to allow access to your account:
architect login
Register a component
Before deploying to a cloud environment, you must register and tag your
component with Architect’s component registry. You can register
the component with a single command, substituting your Architect account name for the <account-name>
placeholder.
Run this command from the top-level directory of your project:
architect register . --tag latest --account <account-name>
The register
command builds the services defined in your architect.yml
file and pushes the artifacts to Architect’s
registry. Once complete, you’ll see output similar to the following.
%architect register .
context "architect-darwin-context" already exists
error: existing instance for architect-darwin but no append mode, specify --node to make changes for existing instances
[+] Building 196.5s (11/12)
[+] Building 303.2s (14/14) FINISHED
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 333B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 58B 0.0s
=> [internal] load metadata for docker.io/library/node:16-alpine 1.7s
=> [auth] library/node:pull token for registry-1.docker.io 0.0s
=> [1/7] FROM docker.io/library/node:16-alpine@sha256:95a849eafc573ad0d972fd67c569369e7aa94d55a21ede3b972e3137e5f8e43a 4.3s
=> => resolve docker.io/library/node:16-alpine@sha256:95a849eafc573ad0d972fd67c569369e7aa94d55a21ede3b972e3137e5f8e43a 0.0s
=> => sha256:4d4a28bae26a20232f7734ee687b79c7b5198349111fb866beb4f6c438abb34b 451B / 451B 0.3s
=> => sha256:6112f742730b6f4181acbc84efd26e9950195948489e1c02b75a83cdd8bf3171 2.35MB / 2.35MB 1.0s
=> => sha256:a67f65df360be748c09d983c17f1fd884f32990a71042c64278c8d8b830b793d 36.73MB / 36.73MB 3.2s
=> => extracting sha256:a67f65df360be748c09d983c17f1fd884f32990a71042c64278c8d8b830b793d 1.0s
=> => extracting sha256:6112f742730b6f4181acbc84efd26e9950195948489e1c02b75a83cdd8bf3171 0.1s
=> => extracting sha256:4d4a28bae26a20232f7734ee687b79c7b5198349111fb866beb4f6c438abb34b 0.0s
=> [internal] load build context 0.1s
=> => transferring context: 1.61MB 0.1s
=> [2/7] RUN apk --no-cache add curl 4.1s
=> [3/7] WORKDIR /usr/src/app 0.0s
=> [4/7] COPY package*.json ./ 0.0s
=> [5/7] RUN npm install 136.0s
=> [6/7] COPY . . 0.4s
=> [7/7] RUN if [ "production" = "development" ] ; then echo "Debug mode enabled. Skipping build." ; else npm run build ; fi 105.6s
=> exporting to image 50.9s
=> => exporting layers 10.7s
=> => exporting manifest sha256:5f3ba9cb2606b94b65e82046c24339c050a6618199f8b80d95fd52ad55808cee 0.0s
=> => exporting config sha256:4070b965df49d7589f590992a0601cf4ddb7a1c16a8ec90eebb46faa202ed119 0.0s
=> => pushing layers 38.1s
=> => pushing manifest for registry.architect.io/devmandy-architect/react.services.app:latest@sha256:5f3ba9cb2606b94b65e82046c24339c050a661819 2.1s
=> [auth] sharing credentials for registry.architect.io 0.0s
Begin component config diff
+ name: react
+ description: |
+ Example component that includes a React frontend
+ homepage: https://github.com/architect-templates/react
+ keywords:
+ - react
+ - express
+ services:
+ app:
+ build:
+ context: ./
+ args:
+ NODE_ENV: production
+ interfaces:
+ main:
+ port: 8080
+ ingress:
+ subdomain: app
+ environment:
+ PORT: 8080
+ entrypoint: /usr/src/app/bin/entrypoint.sh
+ command: npm run start
+ liveness_probe:
+ command: curl --fail 0.0.0.0:8080
+ interval: 30s
+ failure_threshold: 3
+ image: registry.architect.io/devmandy-architect/react.services.app@sha256:5f3ba9cb2606b94b65e82046c24339c050a6618199f8b80d95fd52ad55808cee
End component config diff
Registering component react:latest with Architect Cloud...... done
Successfully registered component
Time: 5:05.597 (m:ss.mmm)
Create an environment
An environment is an isolated namespace that exists on a Kubernetes cluster where you can deploy your applications. Architect provides a community cloud cluster where you can create a preview environment and deploy your applications for free. To create a new environment on Architect’s free cloud, run the following command:
architect environments:create my-first-environment
This command presents you with a list of Kubernetes clusters. Since you haven’t added external clusters to your
account, you should only see architect
. Hit enter to create your environment on the Architect cloud.
? Select a cluster (Use arrow keys or type to search)
❯ architect
When the command completes, you should see output similar to the following:
%architect environments:create my-first-environment
? Select a cluster architect
Registering environment with Architect... done
Environment created: https://cloud.architect.io/<account-name>/environments/my-first-environment
Deploy to the cloud
Finally, you’re ready to deploy! Run the following command to deploy your application to the environment you just created on the Architect cloud:
architect deploy react:latest --account <account-name> \
--environment my-first-environment
Nice work! Now that you’ve gotten the hang of the deploy flow, you can try it out with your own application. Head over to the
configuration section to learn more about the
architect.yml
file and how to write one of your own!