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.

Give it a try! Search inside your project for “Movie Ratings” and change this string to “Pizza Ratings.” Once you save the file, you’ll see the frontend service recompiling in the logs and then your browser window will update automatically.

​
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!

HomeStarter Projects