- Getting Started
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
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
Just download the appropriate bundle, extract it, and link the included
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 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.
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
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
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!
Make your own changes
As you may have noticed, there is a
debug block in the
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:
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
Run this command from the top-level directory of your project:
architect register . --tag latest --account <account-name>
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!