Skip to content
ArchFoundry Docs Open the canvas

Deploy a diagram to your AWS account

Updated November 2, 2026Plans: Free, Pro, Enterprise

Overview

Deploying runs the diagram's Terraform against your AWS account. Before anything is created you see every resource the plan would add, change or destroy, and what it adds to your monthly bill. Nothing happens until you type a word to confirm. The deploy runs in a tab beside the canvas, so you watch each card light up as it is created.

Prerequisites

Steps

  1. On the canvas, click Deploy at the top right. The Deploy tab opens on a summary: one line for each card that will be created, the monthly price, and the account and region it goes to. The heading reads Ready to deploy when nothing more is needed, Almost ready to deploy when something is, and Connect AWS first when no AWS account is connected.
  2. Read the lines. ArchFoundry fills in what it can work out from the diagram: sizes, the database user dbadmin, a bucket name that ends in six random letters and digits, and your repository's branch. An app built from your repository shows a sample page until its first build. An app with no repository shows a sample page: click Pick a repository beside it to choose one. To change a name, click Rename beside it. Below the lines, the summary lists the names your code reads that nothing sets yet, and what to do about each.
  3. If the summary lists something under Still needed, click Fill this in beside it. The form opens on that field. A choice that reads Choose one, such as what the firewall does with bad requests (Count or Block), has to be chosen.
  4. If the summary says some cards are not in a network, click Create a network for this app, or pick one from Use a network I have. To keep the app off the internet, tick Keep the app off the internet first. It adds a monthly cost, shown beside it.
  5. To see or change every setting, click Edit details. The region is under Where this goes; prices are us-east-1 list prices, so other regions cost somewhat more than shown. Optional settings are under More settings on each card. Back to summary returns to the summary.
  6. Click Review changes. Nothing is created yet.
  7. Read the plan: how many resources it would add, change and destroy, each one listed, and the change to your monthly bill. Click Show the Terraform to read it, or use Download main.tf to run it yourself.
  8. Click Create these followed by the number of resources. For a stack that already stands, the button reads Apply followed by the number of changes.
  9. Type the word shown under Type create to confirm, then click Create them. If the account is named as an environment, the word is that name, for example prod.
  10. Watch the cards light up as Terraform reaches them. Click Show log for the detail. Once it starts, nothing in ArchFoundry can stop it: Terraform runs on the server and finishes even if you close the browser.

Example

The confirmation screen for a small web app reads:

text
Create 17 resources in us-east-1?
+$54.51/month
This bills to your AWS account from the moment it succeeds, whether or not anything uses it.
You can remove these later from Deploy → What you have running.
Type create to confirm

Expected result: the deploy finishes with the resources created. The message says They exist and they are billing. Everything you deploy appears in Deployments.

Verify it worked

  • The top bar says the diagram is deployed, with the region and how many nodes are standing.
  • In Deployments, the stack is listed with its account, state, monthly cost and health.
  • On the canvas, open the Deploy button's menu and choose Check traffic… to ask the load balancer whether it serves.

What is recorded for each change

Once ArchFoundry has turned change records on, every deploy, update, fix and destroy leaves a record, whether it finished or not. A record says:

  • which resources changed, and for an update, each setting's old and new value. A secret value reads (sensitive), never the value itself.
  • who asked for the change (you, or a coding agent and the person it works for), who approved it, and their role.
  • the environment name of the AWS account, and the monthly cost before and after.
  • the card on your diagram each resource came from, and why that card is there, as Archie wrote it.
  • the first health check after the change: serving or not_serving.

Any member of your organization can read a stack's records, newest first, up to 200. There is no screen for them yet. While signed in, open this address to list every stack, including removed ones, each with its id:

text
https://app.archfoundry.ai/api/deployments

Then open this one, with that id in place of <deployment-id>:

text
https://app.archfoundry.ai/api/deployments/<deployment-id>/changes

If the answer reads "available": false, records cannot be read right now; your deploys are not affected. Records start with changes made after this feature shipped.

Troubleshooting

Connect your AWS account to deploy. No AWS account is connected yet. Click Connect AWS on the summary. See Connect your AWS account.

Not shaped like an AWS region. Type a region such as us-east-1 or eu-west-2.

Terraform cannot plan without these values. Fill in the fields marked as needing fixing above the button.

The canvas changed since this plan was taken. You edited the diagram after planning. Click Plan again.

This design needs more permissions in your AWS account. Your AWS account's ArchFoundry permissions are older than this design needs. Nothing has been created. Click Add permission in AWS. AWS opens a page that creates a small add-on stack, with every value already filled in. Tick the box that starts "I acknowledge" and click Create stack. Deploy notices by itself and moves on; you do not copy or type anything, and your arcfoundry-deploy stack is not changed. If Deploy says the permissions are not there yet, check you are signed in to the AWS account it names. If it says your AWS sign-in cannot add permissions, ask an admin of that AWS account to click the button. If it says your account has no room for more ArchFoundry permissions, click the button it shows: remove the older permissions ArchFoundry added, or ask AWS for more room. The same button is on the account's row in Cloud accounts, so you can add the permissions before a deploy needs them. To remove the permissions later, delete the stacks whose names start with arcfoundry-addon in CloudFormation.

Or do it by hand. Under the button, Or do it by hand updates your existing stack instead. It is also what Deploy shows when it cannot open AWS for you (a local or preview copy of ArchFoundry), titled More permissions needed. Click Open AWS to open CloudFormation in the right region. Show the steps, or Or do it by hand itself, lists all six; no download is needed, because in step 3 you paste the template's address. 1. In AWS, sign in to the account Deploy names (its alias and account id) and open CloudFormation in the region it names. 2. Select the stack that gives ArchFoundry deploy access. It is usually called arcfoundry-deploy, not arcfoundry-readonly. If the list is empty, change the region at the top right of AWS. Press Update. 3. Choose Replace existing template, then Amazon S3 URL. Click Copy beside the address Deploy shows, paste it, and press Next. To upload the file instead, click Download in step 3, choose Upload a template file, pick the file, and press Next. 4. Press Next on the next page. Keep every setting as it is. 5. Under Capabilities, tick the box that starts "I acknowledge", then press Next. 6. On the last page, press Update stack. It takes a minute or two. When AWS shows the update is complete, come back and click Check again. If AWS says it rolled back, nothing changed: check you picked the right stack, then try again. If AWS says there are no updates to perform, this step is done: wait a minute, then click Check again. A design your coding agent asked for shows this on Deploy's first screen, before you review the changes.

This plan destroys something. ArchFoundry will not delete or replace resources for you in a deploy. Read the list, then destroy the stack and deploy the new shape, or undo the change.

This diagram is deployed to another account. Deploying here would create a second copy rather than update it. Click Switch to that account to update the existing stack.

Archie did not deploy this. The change would turn off a database's automated backups (its backup_retention_period set to 0), and AWS would then delete the backups it kept. Nothing was created or changed. The message names the database card and the value it had. Click Close, set backup_retention_period on that card back to the value named, then click Review changes again.

The apply did not finish. It shows how many resources were created, how many failed and how many were not attempted. The created ones exist and bill. When Archie knows the fix, it shows Archie can fix this. See Check health and fix a failed deploy.

Lost contact with the server while the apply was running. The apply has not been cancelled and is probably still creating resources. Check the AWS console before trying again.

Next steps