](https://www.npmjs.com/package/@architect/architect)
+
+
+ 
+ 
+
${hljs.highlight(lang, str, true).value}${escapeHtml(str)}404: Not found
', +} diff --git a/src/shared/redirect-map.mjs b/src/shared/redirect-map.mjs new file mode 100644 index 00000000..b803eeb4 --- /dev/null +++ b/src/shared/redirect-map.mjs @@ -0,0 +1,277 @@ +export const currentRoot = '/docs/en/get-started/quickstart' + +// these are soft redirects, not forever/canonical +export const tempRedirects = { + // Canonical pragma paths + '/app': '/docs/en/reference/project-manifest/app', + '/@app': '/docs/en/reference/project-manifest/app', + '/aws': '/docs/en/reference/project-manifest/aws', + '/@aws': '/docs/en/reference/project-manifest/aws', + '/events': '/docs/en/reference/project-manifest/events', + '/@events': '/docs/en/reference/project-manifest/events', + '/http': '/docs/en/reference/project-manifest/http', + '/@http': '/docs/en/reference/project-manifest/http', + '/indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/@indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/macros': '/docs/en/reference/project-manifest/macros', + '/@macros': '/docs/en/reference/project-manifest/macros', + '/plugins': '/docs/en/reference/project-manifest/plugins', + '/@plugins': '/docs/en/reference/project-manifest/plugins', + '/proxy': '/docs/en/reference/project-manifest/proxy', + '/@proxy': '/docs/en/reference/project-manifest/proxy', + '/queues': '/docs/en/reference/project-manifest/queues', + '/@queues': '/docs/en/reference/project-manifest/queues', + '/scheduled': '/docs/en/reference/project-manifest/scheduled', + '/@scheduled': '/docs/en/reference/project-manifest/scheduled', + '/shared': '/docs/en/reference/project-manifest/shared', + '/@shared': '/docs/en/reference/project-manifest/shared', + '/static': '/docs/en/reference/project-manifest/static', + '/@static': '/docs/en/reference/project-manifest/static', + '/tables': '/docs/en/reference/project-manifest/tables', + '/@tables': '/docs/en/reference/project-manifest/tables', + '/tables-indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/@tables-indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/tables-streams': '/docs/en/reference/project-manifest/tables-streams', + '/@tables-streams': '/docs/en/reference/project-manifest/tables-streams', + '/views': '/docs/en/reference/project-manifest/views', + '/@views': '/docs/en/reference/project-manifest/views', + '/ws': '/docs/en/reference/project-manifest/ws', + '/@ws': '/docs/en/reference/project-manifest/ws', + + // Runtimes + '/node': '/docs/en/reference/runtime-helpers/node.js', + '/ruby': '/docs/en/reference/runtime-helpers/ruby', + '/python': '/docs/en/reference/runtime-helpers/python', + '/deno': '/docs/en/reference/runtime-helpers/deno', + + // Other aliases + '/typescript': '/docs/en/guides/developer-experience/using-typescript', + '/esm': '/docs/en/guides/developer-experience/using-esm', + '/aws-sdk-versions': '/docs/en/get-started/detailed-aws-setup#aws-sdk', +} + +// redirect known v5/6 arc urls to v8 and then to v9 +export const permanentRedirects = { + '/examples': '/docs/en/guides/examples', + + // Intro + // round 1: Q1 2021 + '/intro/philosophy': '/docs/en/get-started/why-architect', + '/intro/limits': '/docs/en/get-started/detailed-aws-setup', + '/intro/community': '/docs/en/about/contribute', + + // Quickstart + // round 1: Q1 2021 + '/quickstart': '/docs/en/get-started/quickstart', + '/quickstart/install': '/docs/en/get-started/quickstart', + '/quickstart/layout': '/docs/en/get-started/project-manifest', + '/quickstart/what-next': '/docs/en/get-started/quickstart', + + // Primitives + // round 1: Q1 2021 + '/primitives/http': '/docs/en/reference/project-manifest/http', + '/primitives/ws': '/docs/en/reference/project-manifest/ws', + '/primitives/static': '/docs/en/reference/project-manifest/static', + '/primitives/cdn': '/docs/en/reference/project-manifest/static', + '/primitives/scheduled': '/docs/en/reference/project-manifest/scheduled', + '/primitives/events': '/docs/en/reference/project-manifest/events', + '/primitives/queues': '/docs/en/reference/project-manifest/queues', + '/primitives/tables': '/docs/en/reference/project-manifest/tables', + '/primitives/macros': '/docs/en/reference/project-manifest/macros', + + // Guides + // round 1: Q1 2021 + '/guides/upgrade': '/docs/en/about/upgrade-guide', + '/guides/testing': '/docs/en/guides/developer-experience/local-development', + '/guides/project-manifest': '/docs/en/get-started/project-manifest', + '/guides/share-code': '/docs/en/guides/developer-experience/sharing-code', + '/guides/sharing-common-code': '/docs/en/guides/developer-experience/sharing-code', + '/guides/custom-file-paths': '/docs/en/guides/developer-experience/custom-source-paths', + // round 2: Q4 2021 + '/docs/en/guides/get-started/why-architect': '/docs/en/get-started/why-architect', + '/docs/en/guides/get-started/quickstart': '/docs/en/get-started/quickstart', + '/docs/en/guides/get-started/project-layout': '/docs/en/get-started/project-manifest', + '/docs/en/guides/get-started/detailed-aws-setup': '/docs/en/get-started/detailed-aws-setup', + '/docs/en/guides/extend/custom-cloudformation': '/docs/en/guides/developer-experience/custom-cloudformation', + // mid-2022 + '/docs/en/guides/developer-experience/customizing-cloudformation': '/docs/en/guides/developer-experience/custom-cloudformation', + + // Reference > Project Manifest + // round 1: Q1 2021 + '/reference/arc/app': '/docs/en/reference/project-manifest/app', + '/reference/arc/aws': '/docs/en/reference/project-manifest/aws', + '/reference/arc/events': '/docs/en/reference/project-manifest/events', + '/reference/arc/http': '/docs/en/reference/project-manifest/http', + '/reference/arc/indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/reference/arc/proxy': '/docs/en/reference/project-manifest/proxy', + '/reference/arc/queues': '/docs/en/reference/project-manifest/queues', + '/reference/arc/scheduled': '/docs/en/reference/project-manifest/scheduled', + '/reference/arc/static': '/docs/en/reference/project-manifest/static', + '/reference/arc/tables': '/docs/en/reference/project-manifest/tables', + '/reference/arc/ws': '/docs/en/reference/project-manifest/ws', + // round 2: Q4 2021 + '/docs/en/reference/app.arc/app': '/docs/en/reference/project-manifest/app', + '/docs/en/reference/app.arc/aws': '/docs/en/reference/project-manifest/aws', + '/docs/en/reference/app.arc/events': '/docs/en/reference/project-manifest/events', + '/docs/en/reference/app.arc/http': '/docs/en/reference/project-manifest/http', + '/docs/en/reference/app.arc/indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/docs/en/reference/app.arc/proxy': '/docs/en/reference/project-manifest/proxy', + '/docs/en/reference/app.arc/queues': '/docs/en/reference/project-manifest/queues', + '/docs/en/reference/app.arc/scheduled': '/docs/en/reference/project-manifest/scheduled', + '/docs/en/reference/app.arc/shared': '/docs/en/reference/project-manifest/shared', + '/docs/en/reference/app.arc/static': '/docs/en/reference/project-manifest/static', + '/docs/en/reference/app.arc/tables': '/docs/en/reference/project-manifest/tables', + '/docs/en/reference/app.arc/views': '/docs/en/reference/project-manifest/views', + '/docs/en/reference/app.arc/ws': '/docs/en/reference/project-manifest/ws', + // rename @indexes => @tables-indexes + '/docs/en/reference/project-manifest/indexes': '/docs/en/reference/project-manifest/tables-indexes', + + // Reference > Configuration > Function config + // round 1: Q1 2021 + '/reference/arc-config/aws': '/docs/en/reference/configuration/function-config', + '/reference/arc-config/runtime': '/docs/en/reference/configuration/function-config#runtime', + '/reference/arc-config/memory': '/docs/en/reference/configuration/function-config#memory', + '/reference/arc-config/timeout': '/docs/en/reference/configuration/function-config#timeout', + '/reference/arc-config/concurrency': '/docs/en/reference/configuration/function-config#concurrency', + '/reference/arc-config/layers': '/docs/en/reference/configuration/function-config#layers', + '/reference/arc-config/policies': '/docs/en/reference/configuration/function-config#policies', + // round 2: Q4 2021 + '/docs/en/reference/config.arc/aws': '/docs/en/reference/configuration/function-config', + '/docs/en/reference/config.arc/runtime': '/docs/en/reference/configuration/function-config#runtime', + '/docs/en/reference/config.arc/memory': '/docs/en/reference/configuration/function-config#memory', + '/docs/en/reference/config.arc/timeout': '/docs/en/reference/configuration/function-config#timeout', + '/docs/en/reference/config.arc/concurrency': '/docs/en/reference/configuration/function-config#concurrency', + '/docs/en/reference/config.arc/layers': '/docs/en/reference/configuration/function-config#layers', + '/docs/en/reference/config.arc/policies': '/docs/en/reference/configuration/function-config#policies', + '/docs/en/reference/config.arc/architecture': '/docs/en/reference/configuration/function-config#architecture', + + // Reference > Configuration > Local preferences + // round 1: Q1 2021 + '/reference/preferences#create': '/docs/en/reference/configuration/local-preferences#@create', + '/reference/preferences#env': '/docs/en/reference/configuration/local-preferences#@env', + '/reference/preferences#.env': '/docs/en/reference/configuration/local-preferences#@env', + '/reference/preferences#sandbox': '/docs/en/reference/configuration/local-preferences#@sandbox', + // round 2: Q4 2021 + '/docs/en/reference/prefs.arc/create': '/docs/en/reference/configuration/local-preferences#@create', + '/docs/en/reference/prefs.arc/env': '/docs/en/reference/configuration/local-preferences#@env', + '/docs/en/reference/prefs.arc/.env': '/docs/en/reference/configuration/local-preferences#@env', + '/docs/en/reference/prefs.arc/sandbox': '/docs/en/reference/configuration/local-preferences#@sandbox', + '/docs/en/reference/prefs.arc/sandbox-startup': '/docs/en/reference/configuration/local-preferences#@sandbox-start', + + // Reference > CLI + // round 1: Q1 2021 + '/reference/cli/deploy': '/docs/en/reference/cli/deploy', + '/reference/cli/package': '/docs/en/reference/cli/deploy', + '/reference/cli/destroy': '/docs/en/reference/cli/destroy', + '/reference/cli/env': '/docs/en/reference/cli/env', + '/reference/cli/init': '/docs/en/reference/cli/init', + '/reference/cli/logs': '/docs/en/reference/cli/logs', + '/reference/cli/sandbox': '/docs/en/reference/cli/sandbox', + '/reference/cli/hydrate': '/docs/en/reference/cli/sandbox', + // round 2: Q4 2021 - no change + + // Reference > Runtime helpers + // round 1: Q1 2021 + '/reference/functions/events': '/docs/en/reference/runtime-helpers/node.js', + '/reference/functions/http': '/docs/en/reference/runtime-helpers/node.js', + '/reference/functions/http/node/async': '/docs/en/reference/runtime-helpers/node.js', + '/reference/functions/queues': '/docs/en/reference/runtime-helpers/node.js', + '/reference/functions/static': '/docs/en/reference/runtime-helpers/node.js', + '/reference/functions/tables': '/docs/en/reference/runtime-helpers/node.js', + '/reference/functions/ws': '/docs/en/reference/runtime-helpers/node.js', + // round 2: Q4 2021 + '/docs/en/reference/runtime/node': '/docs/en/reference/runtime-helpers/node.js', + '/docs/en/reference/runtime/node.js': '/docs/en/reference/runtime-helpers/node.js', + '/docs/en/reference/runtime/deno': '/docs/en/reference/runtime-helpers/deno', + '/docs/en/reference/runtime/ruby': '/docs/en/reference/runtime-helpers/ruby', + '/docs/en/reference/runtime/python': '/docs/en/reference/runtime-helpers/python', + + // v5 and v6 archive + // round 1 addendum + // TODO: revisit these as new guides and tutorials are added + '/guides/http': '/docs/en/reference/runtime-helpers/node.js#arc.http', + '/guides/offline': '/docs/en/guides/developer-experience/local-development', + '/guides/static-assets': '/docs/en/guides/frontend/static-assets', + '/guides/spa': '/docs/en/reference/runtime-helpers/node.js#@architect/asap', + '/guides/sessions': '/docs/en/reference/runtime-helpers/node.js#arc.http.session', + '/guides/middleware': '/docs/en/reference/runtime-helpers/node.js#arc.http', + '/guides/data': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/guides/background-tasks': '/docs/en/reference/runtime-helpers/node.js#arc.events', + '/guides/cors': '/docs/en/reference/runtime-helpers/node.js#responses', + '/guides/logging': '/docs/en/guides/developer-experience/logging-and-monitoring', + '/guides/custom-dns': '/docs/en/guides/domains/overview', + '/guides/ws': '/docs/en/reference/runtime-helpers/node.js#arc.ws', + '/guides/documentdb': currentRoot, + '/guides/multiple-aws-accounts': '/docs/en/get-started/detailed-aws-setup', + '/guides/iam': '/docs/en/get-started/detailed-aws-setup', + '/guides/yaml-and-json': '/docs/en/get-started/project-manifest', + '/guides/deps': '/docs/en/guides/developer-experience/dependency-management', + '/reference/arc-audit': currentRoot, + '/reference/arc-config': currentRoot, + '/reference/arc-create': '/docs/en/reference/cli/init', + '/reference/arc-deploy': '/docs/en/reference/cli/deploy', + '/reference/arc-dns': currentRoot, + '/reference/arc-env': '/docs/en/reference/cli/env', + '/reference/arc-hydrate': '/docs/en/reference/cli/hydrate', + '/reference/arc-inventory': currentRoot, + '/reference/arc-logs': '/docs/en/reference/cli/logs', + '/reference/arc-repl': currentRoot, + '/reference/arc-sandbox': '/docs/en/reference/cli/sandbox', + '/reference/app': '/docs/en/reference/project-manifest/app', + '/reference/aws': '/docs/en/reference/project-manifest/aws', + '/reference/domain': currentRoot, + '/reference/events': '/docs/en/reference/project-manifest/events', + '/reference/http': '/docs/en/reference/project-manifest/http', + '/reference/indexes': '/docs/en/reference/project-manifest/tables-indexes', + '/reference/queues': '/docs/en/reference/project-manifest/queues', + '/reference/scheduled': '/docs/en/reference/project-manifest/scheduled', + '/reference/static': '/docs/en/reference/project-manifest/static', + '/reference/tables': '/docs/en/reference/project-manifest/tables', + '/reference/ws': '/docs/en/reference/project-manifest/ws', + '/reference/events-publish': '/docs/en/reference/runtime-helpers/node.js#arc.events', + '/reference/events-subscribe': '/docs/en/reference/runtime-helpers/node.js#arc.events', + '/reference/http-functions': '/docs/en/reference/runtime-helpers/node.js#arc.http', + '/reference/http-helpers': '/docs/en/reference/runtime-helpers/node.js#arc.http', + '/reference/http-session': '/docs/en/reference/runtime-helpers/node.js#arc.http.session', + '/reference/middleware': '/docs/en/reference/runtime-helpers/node.js#arc.http', + '/reference/proxy-public': '/docs/en/reference/runtime-helpers/node.js#@architect/Fasap', + '/reference/proxy-read': '/docs/en/reference/runtime-helpers/node.js#@architect/Fasap', + '/reference/queues-publish': '/docs/en/reference/runtime-helpers/node.js#arc.queues', + '/reference/queues-subscribe': '/docs/en/reference/runtime-helpers/node.js#arc.queues', + '/reference/tables-destroy': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/tables-insert': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/tables-update': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/ws-functions': '/docs/en/reference/runtime-helpers/node.js#arc.ws', + '/reference/data': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-name': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-db': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-doc': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-get': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-query': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-scan': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-put': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-update': '/docs/en/reference/runtime-helpers/node.js#arc.tables', + '/reference/data-delete': '/docs/en/reference/runtime-helpers/node.js#arc.tables', +} + +export async function redirect (req) { + const reqPath = req.requestContext.http.path + const isGet = req.requestContext.http.method.toLowerCase() === 'get' + + if (isGet && (tempRedirects[reqPath] || permanentRedirects[reqPath])) { + const env = process.env.ARC_ENV + const url = (stage, path) => `https://${stage}arc.codes${path}` + + let location = tempRedirects[reqPath] || permanentRedirects[reqPath] + if (env === 'staging') location = url('staging.', location) + if (env === 'production') location = url('', location) + + return { + statusCode: tempRedirects[reqPath] ? 302 : 301, + headers: { + location, + }, + } + } + return +} diff --git a/src/views/docs/en/:tutorials/beyond-hello-world.md b/src/views/docs/en/:tutorials/beyond-hello-world.md new file mode 100644 index 00000000..674455eb --- /dev/null +++ b/src/views/docs/en/:tutorials/beyond-hello-world.md @@ -0,0 +1,14 @@ +--- +title: 'Going Beyond "Hello World"' +category: Tutorials +description: Next steps in developing an application with Architect +sections: + - "Static assets + CDNs" + - "Database tables" + - "Environment variables" + - "CI/CD" + - "Event functions" + - "Scheduled Functions" + - "Queue functions" + - "Macros" +--- diff --git a/src/views/docs/en/:tutorials/configuring-aws.md b/src/views/docs/en/:tutorials/configuring-aws.md new file mode 100644 index 00000000..f98fff9d --- /dev/null +++ b/src/views/docs/en/:tutorials/configuring-aws.md @@ -0,0 +1,130 @@ +--- +title: Configuring AWS +category: Tutorials +description: Set up your Architect project for AWS +sections: + - "Get AWS IAM credentials" + - "Minimum viable permissions" + - "Configure AWS CLI" + - "Working with multiple profiles" + - "Credentials file vs. environment variables" + - "Deploy buckets" + - "Runtime Environments" +--- + +## Get AWS IAM credentials + +You'll need an Amazon Web Services account and credentials set up on your development machine and / or CI systems. If you yet set it up, here's a useful guide for [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html). + +In the context of a deployment tool, Architect requires account credentials with IAM `AdministratorAccess` privileges. In turn, Architect will create and attach least-privilege IAM roles to runtime resources within your application, ensuring strict security boundaries by default. + +> ℹ️ While it is possible to limit Architect's deployment credentials to specific IAM and CloudFormation privileges, such an exercise would only be performative. Credentials capable of creating IAM roles can grant and attach new roles with `AdministratorAccess`. + +On \*nix systems AWS Credentials are listed in: + +```bash +~/.aws/credentials +``` + +Or on Windows systems: + +```bash +C:\Users\USER_NAME\.aws\credentials +``` + +If that file doesn't exist, create it, and add the following: + +```bash +[default] +aws_access_key_id=xxx +aws_secret_access_key=xxx +``` + +> If you prefer, you can also use: *Control Panel » System » Advanced System Settings » Environment Variables*. + +## Minimum viable permissions +... + +## Configure AWS CLI + +The [AWS Command Line Interface](https://docs.aws.amazon.com/cli/) is the main interface for interacting with all parts of AWS using your computer's terminal. Architect uses the AWS CLI to package and deploy your app via CloudFormation. Follow this guide to [installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) for your preferred environment. + +## Working with multiple profiles + +It is possible to configure more than one AWS profile. This example credentials file lists 3 profiles: + +```bash +[default] +aws_access_key_id=xxx +aws_secret_access_key=xxx + +[work] +aws_access_key_id=xxx +aws_secret_access_key=xxx + +[personal] +aws_access_key_id=xxx +aws_secret_access_key=xxx +``` + +## Credentials file vs. environment variables + +While it is recommended to explicitly declare your application's AWS profile and region, you may also want to use a default profile and region on your machine with the following environment variables: + +- `AWS_PROFILE` +- `AWS_REGION` + +To set these variables on Linux, macOS, or UNIX, use `export` in your shell's configuration (e.g. `~/.zshrc` or `~/.bashrc`): + +```bash +export AWS_PROFILE=work +export AWS_REGION=us-west-1 +``` + +Or for Windows, add this to your PowerShell `$profile`: + +```powershell +$env:AWS_PROFILE='work' +$env:AWS_REGION='us-west-1' +``` + +## Deploy buckets +... + +## Runtime environments + +Architect supports the following runtime versions: + +- **Node.js**: `>= 18.x` using `npm` + - Unless otherwise specified in your project manifest, Node.js is the default runtime for new functions +- **Python**: `3.13`, `3.12`, `3.11`, `3.10`, or `3.9` using `pip3` +- **Ruby**: `3.3`, or `3.2` using `bundle` +- **Deno**: `1.6.x` ([under development](../reference/runtime-helpers/deno)) + +> ⚠️ Working locally with the Sandbox requires target runtimes to be available in your `$PATH`. + +Additionally, all other standard AWS-managed runtimes are supported in Architect applications (but may not be supported in [Sandbox](../reference/cli/sandbox)), including: + +- **Go**: `1.x` +- **.NET**: `8`, and `9` +- **Java**: `21`, `17`, `11`, and `8` + +Architect also supports _any custom runtime_ in using either [Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) or [Lambda container images](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html). + +Change a project's default runtime by specifying [an explicit environment](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) or an alias in `app.arc` with [the `@aws` pragma](../reference/project-manifest/aws). + +### Examples + +```arc +# version pins the default runtime to Python 3.13 +@aws +runtime python3.13 +``` + +```arc +# always run the latest supported version of Python +@aws +runtime python +``` + +> ℹ️ This setting can be overridden on a per-function basis with [`config.arc`](../reference/configuration/function-config). diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/overview.md b/src/views/docs/en/:tutorials/set-up-a-domain/overview.md new file mode 100644 index 00000000..6435545f --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/overview.md @@ -0,0 +1,52 @@ +--- +title: Setting up a domain +category: Tutorials +description: Setting up a domain for an Architect application +sections: + - "Overview" + - "DNS guides" + - "Setting up your project" +--- + +## Give your Architect application a proper domain name + +DNS is how you assign a domain name to a deployed app. This guide lists ways to set up custom DNS with several popular DNS providers and we are always happy to accept contributions for steps to use additional providers. + +You may use a free registrar-based DNS to host your domain such as GoDaddy, Namecheap, One, etc., but Route53 is the preferred registrar and DNS management system for Architect users. This is because: + +- It's integrated with Amazon's other cloud services. +- Your DNS will resolve from 15+ locations worldwide, making your website faster for your end-users. +- Route53 is a DNS management system (Smart DNS) compared to all the others, which are merely domain registrars with a limited feature set for manipulating DNS. + +## Setting up your project + +To prepare your arc app for setting up a custom domain, you first have to deploy your app to `staging` and `production`. + +Deploy to a `staging` stack: + +```bash +arc deploy +``` +> Protip: create additional `staging` stacks with `--name` + +Ship a `production` stack: + +```bash +arc deploy production +``` + +All done! + +> Remember to save the two generated `URLs` because we will need to input these into the AWS console in the next steps. + +## DNS guides + +Setting up a custom domain for each registrar will be a bit different. To manually configure DNS, you can follow these guides below: + + +- [Route53](/docs/en/guides/domains/registrars/route53) +- [Route53 & CloudFront](/docs/en/guides/domains/registrars/route53-and-cloudfront) +- [Dreamhost](/docs/en/guides/domains/registrars/dreamhost) +- [GoDaddy](/docs/en/guides/domains/registrars/godaddy) +- [Namecheap](/docs/en/guides/domains/registrars/namecheap) +- [One](/docs/en/guides/domains/registrars/one) diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/registrars/dreamhost.md b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/dreamhost.md new file mode 100644 index 00000000..46dc140a --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/dreamhost.md @@ -0,0 +1,62 @@ +--- +title: Dreamhost +category: Domain Registrars +description: Setting up a domain name with Dreamhost +--- + +## Prerequisites + +- Sign up for a domain on [Dreamhost](https://www.dreamhost.com/domains/) +- Make sure your domain is set to `DNS Only` in the Dreamhost console. +- Deploy an app with Architect and make note of the `staging` and `production` URLs +- Make sure your app is deployed to `us-east-1` +- Ensure the `@app` name is uniquely named after the domain. + +## Step 1: setup SSL certificates with AWS Certificate Manager + +In this step we will request a certificate from Amazon for our domain. + +- Open up AWS Certificate Manager in the AWS Console in `us-east-1` (region is required!) +- Click `Request a certificate` and then `Request a public certificate` +- Ensure `example.com` and `*.example.com` for sub domains to work +- Choose `DNS validation` and click `Next` +- Add any tags and confirm the request +- Open up Dreamhost backend and click `Manage Domains` +- Click the `DNS` link under your domain to add custom DNS records +- Create CNAME records of both issued certificates +- Wait until they change from `pending` to `success` + +## Step 2: setup CloudFront + +Generate a CloudFront distribution with the certificate from step 1. + +- Sign into AWS CloudFront in the AWS Console +- Click `Create Distribution` and then click `Get Started` +- Open API Gateway and make note of the Invoke URL. +- Enter the URL from API Gateway in `Origin Domain Name` +- Set `Origin Protocol Policy` to `Match Viewer` +- Add the `Alternate Domain Names (CNAMEs)` that you will be using. ex. `example.com`. +- Set `Viewer Protocol Policy` to `Redirect HTTP to HTTPS` +- Set `Allowed HTTP Methods` to `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE` +- Set `Compress Objects Automatically` to `Yes` +- Set `SSL Certificate` to `Custom SSL Certificate` and select the cert from step 1 +- Click `Create Distribution` +- Repeat for `staging` domain. + +## Step 3: configure the domain Alias in Dreamhost + +Add `Alias` and `CNAME` records to DNS. + +- Sign into Dreamhost +- Navigate to the domain by clicking `Manage Domains` in the sidebar. +- Click `DNS` under the domain +- Click `Add Record` +- Use record type `Alias` for the root domain. + - Leave `Host` input blank and add the CloudFront domain that was created in step 2 to the `Points to` input. +- Use record type `CNAME` for the `staging` domain. + - Add the word `staging` to the `Host` input and add the CloudFront domain that was created in step 2 to the `Points to` input. +- Click `Add records` + +## Conclusion + +Now we're done! You can check to see if your domains are online with the DNS checker tool provided by Dreamhost. You can also use this [DNS Checker tool](https://dnschecker.org/). diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/registrars/godaddy.md b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/godaddy.md new file mode 100644 index 00000000..40e8a635 --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/godaddy.md @@ -0,0 +1,58 @@ +--- +title: GoDaddy +category: Domain Registrars +description: Setting up a domain name with GoDaddy +--- + +## Prerequisites + +- Sign up for a domain on [GoDaddy](https://www.godaddy.com/) +- Deploy an app with Architect and make note of the `staging` and `production` URLs +- Ensure the app is deployed to `us-east-1` +- Ensure the `@app` name is uniquely named after the domain. + +## Step 1: setup SSL certificates with AWS Certificate Manager + +In this step we will request a certificate from Amazon for our domain. + +- Open up AWS Certificate Manager in the AWS Console in `us-east-1` (region is required!) +- Click `Request a certificate` and then `Request a public certificate` +- Ensure `example.com` and `*.example.com` for sub domains to work +- Choose `DNS validation` and click `Next` +- Add any tags and confirm the request +- Open up GoDaddy account dashboard and find the `DNS` settings for the particular domain you want to use. +- Click `ADD` and select `CNAME` +- Create CNAME records of both issued certificates +- Wait until they change from `pending` to `success` + +## Step 2: setup CloudFront + +Generate a CloudFront distribution with the certificate from step 1. + +- Sign into AWS CloudFront in the AWS Console +- Click `Create Distribution` and then click `Get Started` +- Open API Gateway and make note of the `Invoke URL`. +- Enter the URL from API Gateway in `Origin Domain Name` +- Set `Origin Protocol Policy` to `Match Viewer` +- Add the `Alternate Domain Names (CNAMEs)` that you will be using. ex. `example.com`. +- Set `Viewer Protocol Policy` to `Redirect HTTP to HTTPS` +- Set `Allowed HTTP Methods` to `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE` +- Set `Compress Objects Automatically` to `Yes` +- Set `SSL Certificate` to `Custom SSL Certificate` and select the cert from step 1 +- Click `Create Distribution` +- Repeat for `staging` domain. + +## Step 3: configure the domain Alias in GoDaddy + +Add `A` and `CNAME` records to DNS. + +- Open up GoDaddy account dashboard and find the `DNS` settings for the particular domain you want to use. +- Click `ADD`. +- Use record type `A` for the root domain. + - Leave `Host` input empty and add the IP address of the CloudFront domain that was created in step 2 to the `Points to` input. +- Use record type `CNAME` for the `staging` domain. + - Add the word `staging` to the `Host` input and add the CloudFront domain that was created in step 2 to the `Points to` input. + +## Conclusion + +Now we're done! You can check to see if your domains are online with the DNS checker tool [DNS Checker tool](https://dnschecker.org/). diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/registrars/namecheap.md b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/namecheap.md new file mode 100644 index 00000000..0b8caae8 --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/namecheap.md @@ -0,0 +1,60 @@ +--- +title: Namecheap +category: Domain Registrars +description: Setting up a domain name with Namecheap +--- + +## Prerequisites + +- Sign up for a domain on [Namecheap](https://www.Namecheap.com/domains/) +- Deploy an app with Architect and make note of the `staging` and `production` URLs +- Make sure your app is deployed to `us-east-1` +- Ensure the `@app` name is uniquely named after the domain. + +## Step 1: setup SSL certificates with AWS Certificate Manager + +In this step we will request a certificate from Amazon for our domain. + +- Open up AWS Certificate Manager in the AWS Console in `us-east-1` (region is required!) +- Click `Request a certificate` and then `Request a public certificate` +- Ensure `example.com` and `*.example.com` for sub domains to work +- Choose `DNS validation` and click `Next` +- Add any tags and confirm the request +- Open up Namecheap account dashboard and click `Manage` for the particular domain you want to use. +- Open the `Advanced DNS` tab. +- Click `ADD A NEW RECORD` +- Create CNAME records of both issued certificates +- Wait until they change from `pending` to `success` + +## Step 2: setup CloudFront + +Generate a CloudFront distribution with the certificate from step 1. + +- Sign into AWS CloudFront in the AWS Console +- Click `Create Distribution` and then click `Get Started` +- Open API Gateway and make note of the `Invoke URL`. +- Enter the URL from API Gateway in `Origin Domain Name` +- Set `Origin Protocol Policy` to `Match Viewer` +- Add the `Alternate Domain Names (CNAMEs)` that you will be using. ex. `example.com`. +- Set `Viewer Protocol Policy` to `Redirect HTTP to HTTPS` +- Set `Allowed HTTP Methods` to `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE` +- Set `Compress Objects Automatically` to `Yes` +- Set `SSL Certificate` to `Custom SSL Certificate` and select the cert from step 1 +- Click `Create Distribution` +- Repeat for `staging` domain. + +## Step 3: configure the domain Alias in Namecheap + +Add `Alias` and `CNAME` records to DNS. + +- Open up Namecheap account dashboard and click `Manage` for the particular domain you want to use. +- Open the `Advanced DNS` tab. +- Click `ADD A NEW RECORD` +- Use record type `Alias` for the root domain. + - Add `@` in the `Host` input and add the CloudFront domain that was created in step 2 to the `Value` input. +- Use record type `CNAME` for the `staging` domain. + - Add the word `staging` to the `Host` input and add the CloudFront domain that was created in step 2 to the `Value` input. + +## Conclusion + +Now we're done! You can check to see if your domains are online with the DNS checker tool [DNS Checker tool](https://dnschecker.org/). diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/registrars/one.md b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/one.md new file mode 100644 index 00000000..f17bb460 --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/one.md @@ -0,0 +1,60 @@ +--- +title: One +category: Domain Registrars +description: Setting up a domain name with One +--- + +## Prerequisites + +- Sign up for a domain on [One](https://www.one.com/en/domain) +- Deploy an app with Architect and make note of the `staging` and `production` URLs +- Ensure the app is deployed to `us-east-1` +- Ensure the `@app` name is uniquely named after the domain. + +## Step 1: setup SSL certificates with AWS Certificate Manager + +In this step we will request a certificate from Amazon for our domain. + +- Open up AWS Certificate Manager in the AWS Console in `us-east-1` (region is required!) +- Click `Request a certificate` and then `Request a public certificate` +- Ensure `example.com` and `*.example.com` for sub domains to work +- Choose `DNS validation` and click `Next` +- Add any tags and confirm the request +- Open up One account dashboard and click `DNS settings` for the particular domain you want to use. +- Open the `DNS records` tab. +- Click the `CNAME` tab in the `Create new record` box +- Create CNAME records of both issued certificates +- Wait until they change from `pending` to `success` + +## Step 2: setup CloudFront + +Generate a CloudFront distribution with the certificate from step 1. + +- Sign into AWS CloudFront in the AWS Console +- Click `Create Distribution` and then click `Get Started` +- Open API Gateway and make note of the `Invoke URL`. +- Enter the URL from API Gateway in `Origin Domain Name` +- Set `Origin Protocol Policy` to `Match Viewer` +- Add the `Alternate Domain Names (CNAMEs)` that you will be using. ex. `example.com`. +- Set `Viewer Protocol Policy` to `Redirect HTTP to HTTPS` +- Set `Allowed HTTP Methods` to `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE` +- Set `Compress Objects Automatically` to `Yes` +- Set `SSL Certificate` to `Custom SSL Certificate` and select the cert from step 1 +- Click `Create Distribution` +- Repeat for `staging` domain. + +## Step 3: configure the domain Alias in One + +Add `A` and `CNAME` records to DNS. + +- Open up One account dashboard and click `DNS settings` for the particular domain you want to use. +- Open the `DNS records` tab. +- Click the `A` tab in the `Create new record` box +- Use record type `A` for the root domain. + - Leave `Hostname` input empty and add the IP address of the CloudFront domain that was created in step 2 to the `Will point to` input. +- Use record type `CNAME` for the `staging` domain. + - Add the word `staging` to the `Hostname` input and add the CloudFront domain that was created in step 2 to the `Is an alias of` input. + +## Conclusion + +Now we're done! You can check to see if your domains are online with the DNS checker tool [DNS Checker tool](https://dnschecker.org/). diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/registrars/route53-and-cloudfront.md b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/route53-and-cloudfront.md new file mode 100644 index 00000000..5e00cab5 --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/route53-and-cloudfront.md @@ -0,0 +1,53 @@ +--- +title: Route53 & CloudFront +category: Domain Registrars +description: Setting up a domain name with Route53 and CloudFront +--- + +## Prerequisites + +- [Register](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) or [transfer](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-transfer-to-route-53.html) a domain with Route53 +- Deploy an app with Architect and make note of the `staging` and `production` URLs + +## Step 1: setup SSL certificates with AWS Certificate Manager + +In this step we will request a certificate from Amazon for our domain. + +- Open up AWS Certificate Manager in the AWS Console in `us-east-1` (region is required!) +- Click `Request a certificate` and then `Request a public certificate` +- Ensure `example.com` and `*.example.com` for sub domains to work +- Choose `DNS validation` and click `Next` +- Add any tags and confirm the request +- Expand the domain and click `Create record in Route53` button +- Verify CNAME record created in Route53 console Hosted zone + +## Step 2: setup CloudFront + +Generate a CloudFront distribution with the certificate from step 1. + +- Sign into AWS CloudFront in the AWS Console +- Click `Create Distribution` and then click `Get Started` +- Enter the URL from API Gateway in `Origin Domain Name` +- Set `Origin Protocol Policy` to `Match Viewer` +- Set `Viewer Protocol Policy` to `Redirect HTTP to HTTPS` +- Set `Allowed HTTP Methods` to `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE` +- Set `Compress Objects Automatically` to `Yes` +- Enter the domain alias in `Alternate Domain Names` (which you will configure in step 3) +- Set `SSL Certificate` to `Custom SSL Certificate` and select the cert from step 1 +- Click `Create Distribution` + +## Step 3: configure the domain Alias in AWS Route53 + +- Sign into AWS Route53 in the AWS Console +- Navigate to the Hosted zone for the domain +- Click `Create record` +- Enter the `Record name` +- Record type is `A` and toggle `Alias` checkbox on +- Select `Alias to CloudFront` +- Select the region +- Select the CloudFront distribution domain (should be the same value as the domain generated in Step 2) +- Click `Create records` + +## Conclusion + +Now we're done! You can check to see if your domains are online with this [DNS Checker tool](https://dnschecker.org/). diff --git a/src/views/docs/en/:tutorials/set-up-a-domain/registrars/route53.md b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/route53.md new file mode 100644 index 00000000..58491512 --- /dev/null +++ b/src/views/docs/en/:tutorials/set-up-a-domain/registrars/route53.md @@ -0,0 +1,51 @@ +--- +title: Route53 +category: Domain Registrars +description: Setting up a domain name with Route53 +--- + +## Prerequisites + +- [Register](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) or [transfer](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-transfer-to-route-53.html) a domain with Route53 +- Deploy an app with Architect and make note of the `staging` and `production` URLs + +## Step 1: setup SSL certificates with AWS Certificate Manager + +In this step we will request a certificate from Amazon for our domain. + +- Open up AWS Certificate Manager in the AWS Console in `us-east-1` (region is required!) +- Click `Request a certificate` and then `Request a public certificate` +- Ensure `example.com` and `*.example.com` for sub domains to work +- Choose `DNS validation` and click `Next` +- Add any tags and confirm the request +- Expand the domain and click `Create record in Route53` button +- Verify CNAME record created in Route53 console Hosted zone + +## Step 2: setup custom domain with AWS API Gateway + +Generate a domain with the certificate from Step 1. + +- Sign into AWS API Gateway in the AWS Console +- Navigate to `Custom domain names` and click `Create` +- Enter the domain name (e.g. `staging.example.com` for the `staging` app or `example.com` for the `production` app) +- Select the certificate created in Step 1 +- Click `Create domain name` +- Make note of the generated `API Gateway domain name` in `Endpoint configuration` +- Click on the tab `API mappings` and `Configure API mappings` +- For `API` select the API and for `Stage` select `$default` and click `Save` + +## Step 3: configure the domain Alias in AWS Route53 + +- Sign into AWS Route53 in the AWS Console +- Navigate to the Hosted zone for the domain +- Click `Create record` +- Enter the `Record name` +- Record type is `A` and toggle `Alias` checkbox on +- Select `Alias to API Gateway` +- Select the region +- Select the API (should be the same value as the domain generated in Step 2) +- Click `Create records` + +## Conclusion + +Now we're done! You can check to see if your domains are online with this [DNS Checker tool](https://dnschecker.org/). diff --git a/src/views/docs/en/:tutorials/using-plugins.md b/src/views/docs/en/:tutorials/using-plugins.md new file mode 100644 index 00000000..a7c3efc0 --- /dev/null +++ b/src/views/docs/en/:tutorials/using-plugins.md @@ -0,0 +1,14 @@ +--- +title: Using Architect plugins +category: Tutorials +description: Install and use Arc plugins +sections: + - "Overview" + - "Installation" + - "Plugin API" + - "Helper methods" + - "Examples" + # - "Modeling & persisting data" + # - "Building single page apps (SPAs); include aliasing" + # - "Implementing CORS" +--- diff --git a/src/views/docs/en/about/community.md b/src/views/docs/en/about/community.md index 5d8f54e0..71fad68e 100644 --- a/src/views/docs/en/about/community.md +++ b/src/views/docs/en/about/community.md @@ -6,7 +6,7 @@ description: Architect is an open source project and we want YOUR help! Architect is an open source project hosted by the [OpenJS Foundation](https://openjsf.org) and it is totally ok to ask for help! Use the issue tracker to file bugs, request features, or even just to ask a question. -- [Come chat with us in Slack](https://join.slack.com/t/architecture-as-text/shared_invite/MjE2MzU4Nzg0NTY1LTE1MDA2NzgyMzYtODE2NzRkOGRmYw) +- [Come chat with us in Discord](https://discord.gg/y5A2eTsCRX) - [🌟 `@architect/architect` on GitHub](https://github.com/architect/architect) - [Learn how to contribute](/docs/en/about/contribute) @@ -26,3 +26,6 @@ The `app.arc` manifest takes inspiration from UNIX 'run command' files (like `.v The code was developed building [Begin](https://begin.com) and granted to [JS Foundation](https://js.foundation/) in July of 2017 under the `Apache-2.0` license. +## Community Call + +Join us for our monthly community calls on [Discord](https://discord.gg/y5A2eTsCRX) held on the fourth Wednesday of each month at 10:15 am Pacific Time / 1:15 pm Eastern Time / 18:15 UTC. Meeting agendas will be posted in the announcements channel of the Architect Discord. We will use this time to demo upcoming new features and triage [outstanding issues](https://github.com/architect/architect/issues). Please join us and have your voice heard in the project's direction. diff --git a/src/views/docs/en/about/contribute.md b/src/views/docs/en/about/contribute.md index ece8e4dd..498b372e 100644 --- a/src/views/docs/en/about/contribute.md +++ b/src/views/docs/en/about/contribute.md @@ -1,48 +1,113 @@ --- title: Contributor guide -category: about +category: About description: How to contribute to Architect. --- -Architect is an open source project and you can totally help out! Contributing doesn't just mean landing code. It can be reporting bugs, helping us triage bugs, suggesting new features, writing docs, sharing examples and plain kicking it in our community chat. These are all helpful contributions! +Architect is an open source project and you can totally help out! Contributing doesn't just mean landing code. It can be reporting bugs, helping us triage bugs, suggesting new features, writing docs, sharing examples, and plain kicking it in our community chat. These are all helpful contributions! + + +## Helping out + +We are always happy to review and potentially accept pull request to Architect repositories. In general, we suggest opening an issue and starting a discussion in the [Discord](https://discord.gg/y5A2eTsCRX) before you embark on any large project, as there may be requirements or considerations that you may not be aware of in advance. + +If you have a larger problem to solve or idea for a new feature, please file an issue for community discussion. If you have a time-sensitive problem and need to talk things through, you can almost always find someone online in our [Discord](https://discord.gg/y5A2eTsCRX). (It's also a great place to socialize new ideas and to solicit help on how to model specific [Functional Web App (FWA)](https://fwa.dev) patterns.) + +Please help us by making it easy for us to help you! If you are experiencing a bug, please have a reduced test case and steps to reproduce prepared. In our process, the first step to resolution is to create a failing test case so we can ensure there are no future regressions. By having a reduced case (even just an example project) and steps to reproduce, you will dramatically reduce the time to getting your bug fixed. + ## Agreement to the Architect Code of Conduct -By participating in and contributing to the Architect community — including, but not limited to its open source projects, any related online venues such as GitHub, Slack, and in-person events, etc. — you agree to the Architect Code of Conduct. +By participating in and contributing to the Architect community — including, but not limited to its open source projects, any related online venues such as GitHub, Discord, and in-person events, etc. — you agree to the Architect Code of Conduct. Lack of familiarity with this Code of Conduct is not an excuse for not adhering to it. -## Project Code Structure -The Architect project distribution code is bundled in [`architect/architect`](https://github.com/architect/architect) which also serves as the [primary project issue tracker](https://github.com/architect/architect/issues). +## Project structure -The Architect project is composed of multiple core code repositories on GitHub: +The Architect project distribution code is bundled in [`@architect/architect`](https://github.com/architect/architect) which also serves as the [primary project issue tracker](https://github.com/architect/architect/issues). + +The Architect project is comprised of multiple core repositories: + +- [`@architect/create`](https://github.com/architect/create) - scaffold and generate project code +- [`@architect/deploy`](https://github.com/architect/deploy) - deploy an Architect project +- [`@architect/destroy`](https://github.com/architect/destroy) - destroy an Architect app and its related resources +- [`@architect/env`](https://github.com/architect/env) - read / write project environment variables +- [`@architect/hydrate`](https://github.com/architect/hydrate) - ensures Lambda dependencies are installed and ready for use in an AWS environment +- [`@architect/inventory`](https://github.com/architect/inventory) - enumerate an Architect project (including plugin-generated resources) into a common internal intermediary format +- [`@architect/logs`](https://github.com/architect/logs) - read/write Lambda logs +- [`@architect/package`](https://github.com/architect/package) - consumes an Inventory object, and outputs a CloudFormation document for deployment +- [`@architect/parser`](https://github.com/architect/parser) - parser/lexer for Architect project manifest formats (`app.arc`, `.arc`, `arc.json`, `arc.yaml`, and `arc.yml`) +- [`@architect/sandbox`](https://github.com/architect/sandbox) - local development environment; mocks API Gateway, SNS, SQS, DynamoDB, Lambda, etc. +- [`@architect/utils`](https://github.com/architect/utils) - various shared internal helpers and utilities -- [`architect/parser`](https://github.com/architect/parser) - parser/lexer for arcfile formats (`.arc`, `app.arc`, `arc.json`, `arc.yaml`, `arc.yml` and `arc.toml`) -- [`architect/package`](https://github.com/architect/package) - a pure function that consumes `architect/parser` output and returns a CloudFormation document -- [`architect/deploy`](https://github.com/architect/deploy) - a wrapper for the AWS CLI `package` and `deploy` commands -- [`architect/sandbox`](https://github.com/architect/sandbox) - the local sandbox (mocks API Gateway, SNS, SQS, DynamoDB, and Lambda) -- [`architect/env`](https://github.com/architect/env) - read/write arcfile project environment variables with SSM -- [`architect/hydrate`](https://github.com/architect/hydrate) - ensures function deps are synced (including src/shared and src/views) -- [`architect/logs`](https://github.com/architect/logs) - read/write function CloudWatch logs -- [`architect/create`](https://github.com/architect/create) - code generation Projects built with Architect are encouraged to use the following runtime helper libraries: -- [`architect/functions`](https://github.com/architect/functions) - runtime helpers for NodeJS -- [`architect/functions-python`](https://github.com/architect/functions-python) - runtime helpers for Python -- [`architect/functions-ruby`](https://github.com/architect/functions-ruby) - runtime helpers for Ruby +- [`@architect/functions`](https://github.com/architect/functions) - Lambda runtime helpers for Node.js +- [`architect/functions-python`](https://github.com/architect/functions-python) - Lambda runtime helpers for Python +- [`architect/functions-ruby`](https://github.com/architect/functions-ruby) - Lambda runtime helpers for Ruby > Note: runtime helpers are not required to use Architect; they do make dealing with AWS nicer however -Architect project documentation is in the following repos: -- architect/arc.codes.next - new docs site in progress (version 6+) -- architect/arc.codes - the primary documentation website (version 6) -- architect/v5.arc.codes - version 5 docs site +It is also worthwhile to take a look at Architect's various supported plugins and example repos: -## Helping out +- [`architect/plugins`](https://github.com/architect/plugins) - officially supported plugins for Architect 10+ +- [`architect-examples`](https://github.com/architect-examples) - example Architect apps and projects + + +## Architect releases + +- Architect and its constituent libraries follow [SemVer](https://SemVer.org/), taking into consideration [author-time, deploy-time, and runtime lifecycle stages](https://github.com/architect/architect/issues/938) +- Architect (`@architect/architect`) releases are as deterministic as the `package.json` format allows; this is enforced by the following build dependency requirements: + - All first-order `@architect/architect` dependencies are version-pinned + - All second order `@architect/*` dependencies must use SemVer `~` + - The above versioning (pinning + `~`) do not apply to `devDependencies` + + +### Creating an Architect release + +Architect releases are published via CI / CD, with a degree of manual input. The process for creating a new Architect release looks like this: + +1. In the project to be changed, open a PR + - Ensure test coverage is maintained or added, and that tests pass (of course) + - Ideally: verify your changes locally before asking others to review your work. Sometimes the fastest path to doing this is simply to monkey-patch your local Architect installation +2. If the PR is in good shape and approved by a maintainer, merge the PR to `main` +3. Make sure the `changelog.md` file is updated with the correct version, date, and description of changes +4. Use **`npm version`** to publish a new version (from `main`) + - Tip: make sure you push the git tag created by `npm version` (e.g. `git push && git push --tags`), or the release will not publish to npm +5. Once the build is complete and the new release of your module is live, if necessary, update any other Architect modules that consume this change + - Example: if you publish a new minor or major release of `@architect/package`, you will then have to update `@architect/deploy` to use that new dependency, and publish a new version of that package as well +6. Once all the impacted modules are published, prepare a release of `@architect/architect` + - Bump the changed versions in `@architect/architect` + - Make sure the main Architect `changelog.md` incorporates all the various changelog changes + - Ship the new version of Architect (see: step 4) + + +### Architect module release order + +Due to internal module dependencies, Architect has the following module release order: + +0. `parser` +1. `asap` + `utils` +2. `inventory` +3. `create` + `package` + `hydrate` + `destroy` + `env` + `logs` + `functions` +4. `sandbox` + `deploy` +5. `@architect/architect` + +Per this module release, should you make a SemVer major or minor change in any of the packages earlier the list, many (or possibly all) packages below it will need to be updated and re-published. + +Examples: + +- If you make a SemVer major or minor change to `hydrate`, you will have to consume that change in `sandbox` and `deploy` before publishing `@architect/architect` +- If you make a SemVer major or minor change to `inventory`, you will have to consume that change in all packages in order stages 3, then 4, before publishing `@architect/architect` + + +### Non-reliance on automation for some release processes + +While some projects opt for highly automated module publishing and changelog / release notes, Architect has thus far been successful by utilizing a tight and reliable, albeit more manual, deployment process. -We are always happy to accept a pull request to any of the repositories above. If you have a larger problem to solve or idea for a new feature please file an issue for community discussion. If you're having a time sensitive problem and need to talk things through you can almost always find someone in our community chat. It's also a great place to socialize new ideas and to solicit help on how to model specific serverless patterns. +For example, our release notes are written in plain, highly readable and explanatory language (as opposed to in commit message format). -Please help us by making it easy for us to help you! If you are experiencing a bug, please, have a reduced test case and steps to reproduce prepared. In our process, the first step to resolution is to create a failing test case so we can be sure there are no future regressions. By having a reduced case, even just an example project, and steps to reproduce you will save us all time getting to the fix! +Of course, we are always open to streamlining our processes, so please feel free to suggest improvements. diff --git a/src/views/docs/en/about/ejecting-from-architect.md b/src/views/docs/en/about/ejecting-from-architect.md new file mode 100644 index 00000000..cac60c7d --- /dev/null +++ b/src/views/docs/en/about/ejecting-from-architect.md @@ -0,0 +1,33 @@ +--- +title: Ejecting from Architect +category: Extend +description: Ejecting from Architect +--- + +Architect makes it very easy to cease using it in favor of any another tool or framework, such as AWS SAM. + + +## Ejecting to CloudFormation + +In your project directory, run: + +```bash +npx arc deploy --eject +``` + +This will generate your application's `sam.json` + `sam.yaml` documents, as well as print out the necessary AWS CLI instructions to deploy your application without Architect. + + +## Considerations + +It is worth noting that by ejecting from Architect to "raw" AWS or another framework, you may lose access some or all of the following: + +- Expansive, fast, and customizable local development environment +- Baked-in security + performance defaults +- Automated dependency management +- Workflows for managing environment variables, logs, etc. +- Single-command deployments +- Built in testing, staging, production environments +- Human-centered service discovery for machine-generated AWS resources + +Either way, we at Architect hope we'll see you again in the future! diff --git a/src/views/docs/en/about/mission.md b/src/views/docs/en/about/mission.md index 53919406..6bf06200 100644 --- a/src/views/docs/en/about/mission.md +++ b/src/views/docs/en/about/mission.md @@ -1,6 +1,6 @@ --- title: Mission -category: about +category: About description: Architect's Mission --- diff --git a/src/views/docs/en/about/playground.md b/src/views/docs/en/about/playground.md index 3b31c143..cf42c0a3 100644 --- a/src/views/docs/en/about/playground.md +++ b/src/views/docs/en/about/playground.md @@ -1,6 +1,6 @@ --- title: Playground -category: about +category: About description: Architect's infrastructure as code playground. --- diff --git a/src/views/docs/en/about/upgrade.md b/src/views/docs/en/about/upgrade-guide.md similarity index 65% rename from src/views/docs/en/about/upgrade.md rename to src/views/docs/en/about/upgrade-guide.md index 9f4e3847..c8279332 100644 --- a/src/views/docs/en/about/upgrade.md +++ b/src/views/docs/en/about/upgrade-guide.md @@ -1,9 +1,12 @@ --- -title: Changelog -category: Get started +title: Upgrade guide +category: About description: This document covers upgrading from previous versions of Architect sections: - Overview of Architect versions + - Architect 10 → 11 + - Architect 9 → 10 + - Architect 8 → 9 - Architect 7 → 8 - Architect 6 → 7 - Architect 5 → 6 @@ -17,9 +20,30 @@ This document covers upgrading from previous versions of Architect. As a general philosophy, Architect's core maintainers endeavor to minimize the frequency and impact of breaking changes wherever possible; in many cases, major releases may have no impact on existing applications. +## Releases + +### Architect 11 (Cadborosaurus) + +Architect 11 (Cadborosaurus) is a speed, stability, and security release, marking the first version utilizing [`aws-lite`](https://aws-lite.org) instead of the AWS SDK. Architect 11 now installs significantly faster, with a size on disk of roughly 49 MB, down from 191 MB, a 74% reduction. Arc can now also deploy in seconds with *fast mode*. + +Because Architect no longer includes the AWS SDK, any projects that use it to make calls to AWS services must install the AWS SDK as a dependency. [See more below](#architect-10-→-11). + + +### Architect 10 (Taniwha) + +Architect 10 (Taniwha) is a major feature release, introducing the Architect plugins API, and cleaning up internal legacy code, module APIs, and other bits from earlier on in Architect's history. While few of these changes should impact existing projects, users should still [see below for potential impacts to upgrading](#architect-9-→-10). + + +### Architect 9 (La Chupacabra) + +Architect 9 (La Chupacabra) is primarily a maintenance release, dropping support for Node.js 10.x (now end-of-life) and Node.js 12.x, and removing support for Architect 5 (and lower). + +[See below for potential impacts to upgrading](#architect-8-→-9). + + ### Architect 8 (El Chupacabra) -Architect 8 (El Chupacabra) improves API Gateway `HTTP` APIs by adding [`@proxy`](/docs/en/reference/arc-pragmas/@proxy) support for migrating old APIs, and `any` HTTP method support and `*` catchall syntax, while also improving the default greedy catchall behavior of `get /` to be literal to what's found in the Architect manifest. +Architect 8 (El Chupacabra) improves API Gateway `HTTP` APIs by adding [`@proxy`](/docs/en/reference/project-manifest/proxy) support for migrating old APIs, and `any` HTTP method support and `*` catchall syntax, while also improving the default greedy catchall behavior of `get /` to be literal to what's found in the Architect manifest. Although uncommon, certain Architect applications that use `get /` beyond handling `get` requests to `/` may be impacted by this change. [See more below](#architect-7-→-8). @@ -53,18 +77,189 @@ Architect 4 (Yeti) introduced generic, dependency-free HTTP functions, enhanced --- -### Topics +## Upgrade guides +- [Architect 9 → 10](#architect-10-→-11) +- [Architect 9 → 10](#architect-9-→-10) +- [Architect 8 → 9](#architect-8-→-9) - [Architect 7 → 8](#architect-7-→-8) - [Architect 6 → 7](#architect-6-→-7) - [Architect 5 → 6](#architect-5-→-6) -- [Architect 5 LTS (maintenance schedule)](#architect-5-lts-maintenance-schedule) - [Architect 4 → 5](#architect-4-→-5) - [Architect Functions](#architect-functions) - [Architect Data](#architect-data) --- +## Architect 10 → 11 + +Architect 11 (Cadborosaurus) is a speed, stability, and security release, marking the first version utilizing [`aws-lite`](https://aws-lite.org) instead of the AWS SDK. + +Architect 11 now installs significantly faster, with a size on disk of roughly 49 MB, down from 191 MB (a 74% reduction!). Arc also no longer makes use of the AWS CLI, and can now also deploy in seconds with *fast mode*. + + +### Breaking changes + +- Architect no longer includes any versions of AWS SDK as dependencies. Any projects that use AWS SDK v2 or v3 to make calls to AWS services must install it as a dependency. + - Remedy: run the following command in your project, depending on the AWS SDK version(s) you need: + - AWS SDK v2 - `npm i -D aws-sdk` + - AWS SDK v3 - `npm i -D @aws-sdk/client-apigatewaymanagementapi @aws-sdk/client-dynamodb @aws-sdk/client-s3 @aws-sdk/client-sns @aws-sdk/client-sqs @aws-sdk/client-ssm @aws-sdk/lib-dynamodb` + - Alternative remedy: begin transitioning to [`aws-lite`](https://aws-lite.org), which is 2-5x faster, has nice docs, excellent errors, support for types, and is fully open to community contribution +- Due to the upcoming deprecation of `nodejs16.x` and AWS SDK v2 in Lambda, Architect now defaults to `nodejs20.x` + - Remedy: if you still use SDK v2 in your Lambdas by default, add `@aws runtime nodejs16.x` to your [project manifest](/docs/en/reference/project-manifest/aws#runtime) or any relevant [config.arc files](/docs/en/reference/configuration/function-config) + - However, it must be noted that Lambda is retiring `nodejs16.x` with AWS SDK v2 later this year; as above, we are now encouraging folks to transition to `aws-lite`, where possible +- `arm64` is now the default Lambda architecture + - This change only impacts projects that utilize native modules or Lambda layers with binaries; projects that make use of regular Node.js packages will not be impacted by this change + - Remedy: if your native modules / layers aren't yet available for `arm64` Linux, or you just aren't certain about the state of your dependency tree, add `runtime x86_64` to the `@aws` pragma in your project manifest +- Removed support for Node.js 14.x (now EOL, and no longer available to created in AWS Lambda) +- Resolved mismatch between `RouteSelectionExpression` in deployed Architect apps vs. locally in Sandbox + - The `RouteSelectionExpression` is now `$request.body.action`, meaning WebSocket code running locally can now be the same as in production + - Remedy: if you use custom `@ws` handlers and invoke them in Sandbox, you can remove conditional logic renaming the `message` property to `action`. Everything should now use `action`, like so: `ws.send(JSON.stringify({ action: 'custom-endpoint', ... }))` + + +### Notable changes + +- Added experimental `--fast` flag, which ships project to AWS without waiting around to determine if the deployment completed successfully. Use with care! +- Architect no longer requires the AWS CLI, nor Python. So if you'd like to remove either or both, feel free! +- Deploy no longer writes `sam.json` + `sam.yaml` files upon each deploy + - However, if you do want to see the `sam.json` being deployed, use the `--dry-run` or `--debug|-d` CLI flags + + +### Compatibility with `@architect/functions` + +Arc 11 also ships with Architect Functions 8, which also makes use of `aws-lite`. This is an important upgrade, as version 8 no longer suffers from 500-1000ms cold starts due to instantiating the AWS SDK. Version 8 is now between 2-5x faster, and uses 2-4x less memory. + +Version 8 also introduces two important breaking changes noted below; while we do not recommend using use version 7 due to the deprecation of AWS SDK v2 and ongoing performance issues with AWS SDK v3, you may continue to do so as long as the AWS SDK is installed in your project's dependencies. + +Additionally, you can use Architect Functions 8 in Arc 10 projects. + + +#### DynamoDB client instantiation + +Because the AWS SDK can no longer be assumed to be installed in Architect projects, `@architect/functions` offers a new `aws-lite`-based DynamoDB client (`_client`), and provides an opt-in affordance for using AWS SDK-based DynamoDB clients: +- If you only rely on the DocumentClient (`data._doc`), you may want to just try using the new [`@aws-lite/dynamodb`](https://aws-lite.org/services/dynamodb)-based `_client`, which is functionally the same, but significantly faster +- Code depending on `data._db` or `data._doc` must now instantiate with the `awsSdkClient` boolean option, like so: `await arc.tables({ awsSdkClient: true })` + - Using the `awsSdkClient` option necessitates having AWS SDK v2 or v3 installed, according to your Lambda's Node.js version (v2 for 16.x, v3 for 20.x+) + + +#### Error semantics + +Similar to how AWS SDK v3 introduced breaking changes to error semantics from AWS SDK v2, `aws-lite` errors may also be different. We've taken efforts to ensure the maximum degree of compatibility with both AWS SDK v2 and v3 errors, but they may still vary slightly. +- This only really applies if your error handling relies on specific error properties or values +- If you just `console.log()` your errors, you will be totally fine, and the quality of the errors you get via `aws-lite` will most likely improve with this change +- Note: if you're an AWS SDK v2 user considering migrating to v3, error incompatibility will apply even more so; v3 errors are incompatible with v2, whereas `aws-lite` errors attempt to be compatible with both SDK v2 + v3 where possible + + +#### Backward compatibility + +Again, it should be noted that `@architect/functions` 8 is not a required upgrade; you may continue using `@architect/functions` 7 so long as the AWS SDK is installed in your project's dependencies. + +--- + +## Architect 9 → 10 + +Architect 10 (Taniwha) is a major feature release, introducing the Architect plugins API, and cleaning up internal legacy code, module APIs, and other bits from earlier on in Architect's history. + +Most of Architect 10's breaking changes were internal; most users should not encounter breaking changes when upgrading Architect to v10, and Functions + ASAP to v5. + + +### Removed + +- Removed the `package` command, which was no longer able to represent the final state of Architect projects + - Remedy: its (improved) replacement is now: `deploy --eject` +- Removed support for legacy `.arc-env` env files (initially deprecated in late 2020) + - Remedy: if you are still using a `.arc-env` file, please move your [local env vars to `prefs.arc`](/docs/en/reference/configuration/local-preferences#%40env) or [`.env`](/docs/en/reference/configuration/local-preferences#.env-file-support) +- [Removed `toml` support](https://github.com/architect/architect/discussions/1294) (e.g. `arc.toml`) +- Removed built-in support for the `REST` API Gateway. Support is moved to an external plugin, [`plugin-rest-api`](https://github.com/architect/plugin-rest-api). + + +### Breaking changes + +- The beta plugins API has been largely refactored; wherever possible, hooks from the beta API have been ported to the final shipping plugin API. However, many things changed, so if you authored plugins against the beta API, please refer to the [new plugin documentation](/docs/en/reference/plugins/overview) to ensure compatibility +- Due to ongoing issues with unpredictable behavior with certain external libraries, Architect no longer makes use of the `NODE_ENV` environment variable, nor is it automatically added to deployed apps. + - Remedy: if your code relies on Architect automatically populating `NODE_ENV`, you should add it to your userland environment variables, like so: `npx arc env --add --env testing NODE_ENV testing` (and again for `staging` + `production`) +- All support for bare CLI flags has been removed from Architect commands + - All functionality has been retained, but now proper flags must be used + - Example: `npx arc deploy production` should now be `npx arc deploy --production` +- Sandbox's new automatic port selection should frequently actually improve and un-break common uses of Sandbox in testing. However, if your tests or tools rely on Sandbox's default ports (e.g. `3334` for `@events`), you will need to make some minor changes: + - Remedy: Lambda invocations in Sandbox are now passed an environment variable called `ARC_SANDBOX`, which contains a JSON serialized `ports` property; use this property to obtain the currently configured port for a given service + - Should you need to have consistent, non-automatically-selecting ports for Sandbox's internal services, use Sandbox's standard means for explicitly defining port configuration; **do not merely rely on Sandbox's default ports**, as they should be expected to change at any time +- Breaking change: legacy `@tables` / `@tables-streams` folders (`src/tables/...` and `src/streams/...`) are now deprecated in favor of `src/tables-streams/...` + - Remedy: existing stream functions can simply have their folders renamed to `src/tables-streams/{name}` (or use a custom `src` property on them if you'd prefer to keep your existing folder structure) +- Breaking change: `@indexes` is now fully deprecated + - Remedy: simply change the `@indexes` pragma name to `@tables-indexes`; no other changes are required +- Breaking change: moved legacy API Gateway REST API provisioning to `@architect/plugin-rest-api` plugin; to continue deploying REST APIs with Architect: + - Remedy: install `@architect/plugin-rest-api` to your project's dependencies, add `@plugins architect/plugin-rest-api` and `@aws apigateway rest` to your project manifest + + +### Internal breaking changes + +The following internal changes should not have any impact on Architect users should Architect v10 be paired with Functions v5, but just in case anyone used these somewhat more obscure internal features, environment variables, etc., we'll enumerate the changes here: + +- All Architect modules' CLI APIs have been revamped, and now accept an object containing Inventory +- `@architect/env`'s module API has been significantly revamped; if you use `env` as a module, please refer to its documentation +- The following internal Architect environment variables are no longer used: `ARC_CLOUDFORMATION`, `ARC_HTTP`, `ARC_SANDBOX_PATH_TO_STATIC` +- Inventory structure changes: + - `inv._project.src` now represents the default source tree folder (e.g. `$cwd/src`), while `_project.cwd` (new) refers to the current working directory of the project + - `inv._project.env` is now an object populated by three properties: `local`, `plugins`, and `aws`, each reflecting the env vars found for each context's three environments (`testing`, `staging`, `production`) + - `lambda.handlerFunction` has been renamed to `lambda.handlerMethod` +- Architect now prioritizes the AWS region passed via Inventory params over the `AWS_REGION` env var; in practice this should have no practical effect for most users +- Per Deno's guidelines, Architect now prioritizes `mod.ts|js` handlers in Deno Lambdas over the other supported files; in practice this should have no practical effect unless your handler has both an `index.ts|js` file and a `mod.ts|js` file in its root +- Deprecated `ARC_SANDBOX_ENABLE_CORS` env var option from Sandbox + - Remedy: this option predates Architect's support of `options`, which landed in version 8; handling options requests with an `options` (or `any`) handler is the preferred approach to handling CORS +- Internal change: stopped optimistically populating default `arc-sessions` + `data` tables in Sandbox + - This was a very obscure and quirky holdover behavior from early Architect that differed Sandbox from live AWS behavior + - Remedy: realistically no one ever actually used this feature in production, because to do so would have necessitated defining an `arc-sessions` or `data` table in your project manifest; that said, if you experimented with these default DynamoDB tables and want to use them in production, simply add them to your `@tables` pragma + + +### Important non-breaking change + +In a future major release, Architect will deprecate all non-namespaced environment variables. For now, Architect prefers the namespaced versions of the same env var, but will support both; some examples: + +- `ARC_HTTP_PORT` is preferred to `PORT` in Sandbox +- `ARC_SESSION_TABLE_NAME` is preferred to `SESSION_TABLE_NAME` in Sandbox + +If you key on or use non-namespaced Architect env vars, we suggest changing them over to their namespaced equivalents as soon as is convenient. + + +### Compatibility with `@architect/functions` + +Due to internal breaking changes, `@architect/functions` v4 and below is incompatible with Architect 10. +- Remedy: upgrade `@architect/functions` to v5 or above; all existing functionality has been retained, [see more here](#architect-functions) + +--- + +## Architect 8 → 9 + +Architect 9 (La Chupacabra) is a maintenance release, primarily aimed at removing support for Node.js 10.x (now end-of-life) and Node.js 12.x. With this release, after two years since the release of Architect 6, Architect 5 is no longer supported. + +Additionally, Architect's default runtime is now `nodejs14.x` – if your existing functions do not specify a runtime, they will be automatically and seamlessly upgraded from `nodejs10.x` or `nodejs12.x` to `nodejs14.x`. + + +### Breaking changes + +- Removed support for Node.js 10.x (now EOL, and no longer available to created in AWS Lambda) and Node.js 12.x +- `arc destroy` + - `--app` must now be used to destroy apps, while `--name` may only be used to destroy stacks + - Removed support for deprecated `--nuke` flag +- `arc hydrate` + - Usage remains the same, but its module API has removed support for `hydrate()` in favor of explicit `hydrate.install|update|shared()` methods + + +### Compatibility with `@architect/functions` + +Architect 9 is fully compatible with `@architect/functions`. However, `@architect/functions` 4.0, released alongside Architect 9, has some breaking changes: + +- Removed support for Node.js 10.x (now EOL, and no longer available to created in AWS Lambda); Node.js 12.x will continue to be supported until it is EOL in AWS Lambda +- `arc.http.proxy` is now `@architect/asap`, and has been removed from `@architect/functions` 4.0 +- `arc.http.proxy` calls can now be sent as-is to ASAP + - For more details, please see the [@architect/functions changelog](https://github.com/architect/functions/blob/master/_changelog.md#200-2021-07-25) and [@architect/asap changelog](https://github.com/architect/asap/blob/master/_changelog.md#400-2021-07-25) +- Removed support for handling requests from Architect 5 (and lower) APIs + - Responding to requests has not changed, however! + - Old response semantics from Architect 5 (and lower) will continue to be supported, so you'll always have a clear, clean upgrade path from older Architect projects to newer APIs + +--- + ## Architect 7 → 8 ### Overview @@ -339,7 +534,7 @@ Architect 6 is a milestone release that solves some of the most crucial feedback - This includes Ruby and Python support for the `sandbox` local dev server - It also includes ports of the Architect Functions module for [Ruby](https://github.com/architect/arc-functions-ruby) and [Python](https://github.com/architect/arc-functions-python) - Note: Functions for Ruby and Python is not yet at feature parity with the Node.js version, largely dictated by the availability and consistency of certain lower-level APIs in those runtimes. - - As such, broadly speaking, if using Architect Functions in your [HTTP functions](/en/reference/functions/http-functions) we recommend the Node.js version, which includes the most extensive support for front-end facing use cases. + - As such, broadly speaking, if using Architect Functions in your [HTTP functions](/docs/en/reference/project-manifest/http) we recommend the Node.js version, which includes the most extensive support for front-end facing use cases. - **Architect 6 now provisions CDNs with the `@cdn` pragma** - Finally, provision fast, fully-featured, global CDNs to live in front of your web app - This enables your web application to take advantage of crucial features like edge caching and global points of presence @@ -405,7 +600,7 @@ The following Architect 5 `request` parameters changed in Architect 6: - Still one of `GET`, `POST`, `PATCH`, `PUT`, or `DELETE` - `body` is no longer a pre-parsed object - `body` is now either `null` or a base64-encoded buffer - - `body` must first be decoded, then parsed, to make use of it; Architect provides a handy helper to take care of this for you, see: [parsing HTTP request bodies](/en/reference/functions/http-functions#requests) + - `body` must first be decoded, then parsed, to make use of it; Architect provides a handy helper to take care of this for you, see: [parsing HTTP request bodies](/docs/en/reference/runtime-helpers/node.js#arc.http) - `params` is now `pathParameters` - Still an object containing any URL params, if defined in your HTTP function's path (e.g. `foo` in `GET /:foo/bar`) - `query` is now `queryStringParameters` @@ -501,8 +696,8 @@ Architect version 5 is here! Things we added: -- [WebSocket support](/en/guides/tutorials/adding-websockets-to-your-app) -- [New middleware](/en/reference/runtime-helper-reference/arc-http) - added later in arc 4, and out of the box in Arc 5 +- [WebSocket support](/docs/en/reference/project-manifest/ws) +- [New middleware](/docs/en/reference/runtime-helpers/node.js#arc.http) - added later in arc 4, and out of the box in Arc 5 ### 4.x @@ -607,7 +802,7 @@ exports.handler = arc.http(log, route) 1. Open up IAM in the AWS Console 2. Select **Roles** → **arc-role** 3. Click **Attach Policies** -4. Select **AWSLambdaSQSQueueExecutionRole** +4. Select **`AWSLambdaSQSQueueExecutionRole`** 5. Click **Attach Policy** Now existing functions can publish to SQS queues. @@ -620,9 +815,9 @@ If the command line is more your style you can upgrade with the following: aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaSQSQueueExecutionRole --role-name arc-role ``` -**With NodeJS** +**With Node.js** -If you prefer to script this upgrade you can use the NodeJS `aws-sdk`: +If you prefer to script this upgrade you can use the Node.js `aws-sdk`: ```javascript let aws = require('aws-sdk') @@ -641,36 +836,36 @@ iam.attachRolePolicy({ ### Overview -`@architect/functions` runtime helper library will continue to be actively maintained, and is forwards compatible with Architect 6 → 7 upgrades, and most Architect 5 → 6 upgrades. +`@architect/functions` runtime helper library is actively maintained. Version 5 is required for Architect 10+. Users on Architect 6 - 9 should continue to use Functions v4 (which will work in perpetuity, but not be separately maintained). The Architect Functions module is now also available as a dependency for [Ruby](https://github.com/architect/arc-functions-ruby) and [Python](https://github.com/architect/arc-functions-python) functions. ### Changes +- `arc.http.express` was removed in February 2022, and we recommend using `@vendia/serverless-express` or `serverless-http` as replacement modules +- `arc.http.proxy` (previously `arc.proxy`) was deprecated in July 2021, and is now the standalone `@architect/asap` module + - Its methods are functionally the same - `arc.http.middleware` was deprecated in August 2019, and is now `arc.http.async` - These methods are functionally the same - `arc.http.helpers.static` was deprecated in June 2019, and is now `arc.static` - These methods are functionally the same - Due to some under-the-hood changes, if you use `arc.http.helpers.static` or `arc.static`, you will need to upgrade to `@architect/functions` version `^3.3.4` (or greater) in Architect 6 -- `arc.proxy` was deprecated in May 2020, and is now `arc.http.proxy` - - These methods are functionally the same -In all three cases, these are functionally the same. The old aliases will remain for a while to come, but we suggest moving any deprecated calls over to their new equivalents by mid-2020. +### Does `@architect/functions` work in Architect 10+? -### Does `@architect/functions` work in Architect 7? +Yes! Version 5 is required to work correctly in Architect 10+. -Yes! It is supported by and forwards compatible in Architect 7, including use with HTTP API Lambda v2.0 payloads. +### Does `@architect/functions` work in Architect 6 - 9? -### Does `@architect/functions` work in Architect 6? +Absolutely, version 4.x is supported by Arc 6 - 9, including use with HTTP API Lambda v2.0 payloads (introduced in Arc 7). However, version 5+ is incompatible with Arc 6 - 9. -Yes! It is supported by and forwards compatible in Architect 6. Additionally, it has been expanded to include [`@tables` support for working with data](/en/reference/databases/tables). ### Will `@architect/functions` continue working in Architect 5? -Yes! `@architect/functions` is fully backward compatible with Architect 5. You can safely update this dependency, and expect related bugs to be patched. **However, it is worth noting that the new `tables()` method is an Architect 6-only feature.** +Version 4.x remains largely compatible with Architect 5; version 5+ is no longer backward compatible with Architect 5 (support for which officially ended in July of 2021). --- @@ -681,7 +876,7 @@ As of the release of Architect 6, the **Architect Data module (`@architect/data` ### Overview -`@architect/data` will no longer be maintained, and upgrading to Architect 6 will likely be a breaking change. +`@architect/data` will no longer be maintained, and upgrading to Architect 6 will likely be a breaking change for `@architect/data` usage. ### Does `@architect/data` work in Architect 6? @@ -699,7 +894,7 @@ If you built your `@architect/data` calls with `async/await`, `@architect/functi ### Example of `@architect/data` → `@architect/functions` `tables()` #### `@architect/data` before: -```js +```javascript // src/http/get-index/index.js let data = require('@architect/data') @@ -712,7 +907,7 @@ exports.handler = async () => { #### `@architect/functions` `tables()` after: -```js +```javascript // src/http/get-index/index.js let {tables} = require('@architect/functions') @@ -723,4 +918,3 @@ exports.handler = async () => { return {body} } ``` - diff --git a/src/views/docs/en/app-limits.md b/src/views/docs/en/app-limits.md new file mode 100644 index 00000000..1afafe4c --- /dev/null +++ b/src/views/docs/en/app-limits.md @@ -0,0 +1,4 @@ +--- +title: App limits +category: Architect +--- diff --git a/src/views/docs/en/faq.md b/src/views/docs/en/faq.md new file mode 100644 index 00000000..5943529b --- /dev/null +++ b/src/views/docs/en/faq.md @@ -0,0 +1,4 @@ +--- +title: FAQ +category: Architect +--- diff --git a/src/views/docs/en/get-started/detailed-aws-setup.md b/src/views/docs/en/get-started/detailed-aws-setup.md new file mode 100644 index 00000000..2a565979 --- /dev/null +++ b/src/views/docs/en/get-started/detailed-aws-setup.md @@ -0,0 +1,200 @@ +--- +title: Detailed AWS setup +category: Get started +description: Setting up, installing, and working with Architect and AWS. +--- + +> To work locally all you need is [Node](https://nodejs.org), any additional [supported runtimes](#runtime-environments) you plan to use, and the [Architect CLI](#install-architect). + +## AWS deployment requirements + +1. [Node.js](https://nodejs.org) for Architect +2. Any additional [supported runtimes](#runtime-environments) you plan to use in your application +3. [AWS credentials](#credentials) +4. [Architect CLI](#install-architect) + +--- + +### Runtime environments + +Architect supports the following runtimes for composing your application's business logic: + +- **Node.js**: >= 18.x using `npm` + - Unless otherwise specified in your project manifest, Node.js 22.x is the default runtime for new functions +- **Python**: >= 3.9 using `pip3` + - Unless otherwise specified in your project manifest, Python 3.13 is the default Python runtime +- **Ruby**: >= 3.2 using `bundle` +- **Deno**: `1.6.x` ([under development](../reference/runtime-helpers/deno)) + +> ⚠️ Working locally with the Sandbox requires target runtimes to be available in your `$PATH`. + +Additionally, other standard AWS-managed runtimes are supported in Architect applications (but may not be supported in [Sandbox](../reference/cli/sandbox)). Learn more about [Architect's runtime support](/docs/en/get-started/runtime-support). + +Architect also supports _any custom runtime_ in using either [Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) or [Lambda container images](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html). + +Change a project's default runtime by specifying [an explicit environment](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) or an alias in `app.arc` with [the `@aws` pragma](../reference/project-manifest/aws). + +#### Examples + +```arc +# version pins the default runtime to Python 3.13 +@aws +runtime python3.13 +``` + +```arc +# always run the latest supported version of Python +@aws +runtime python +``` + +> ℹ️ This setting can be overridden on a per-function basis with [`config.arc`](../reference/configuration/function-config). + +--- + +### Credentials + +You'll need an Amazon Web Services account and credentials set up on your development machine and / or CI systems. If you don't yet have credentials on your development machine (like from [configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)), here's a guide for [gathering credentials from the AWS Console](../guides/developer-experience/create-aws-credentials). + +In the context of a deployment tool, Architect requires account credentials with IAM `AdministratorAccess` privileges. In turn, Architect will create and attach least-privilege IAM roles to runtime resources within your application, ensuring strict security boundaries by default. + +> ℹ️ While it is possible to limit Architect's deployment credentials to specific IAM and CloudFormation privileges, such an exercise would only be performative. Credentials capable of creating IAM roles can grant and attach new roles with `AdministratorAccess`. + +On \*nix systems AWS Credentials are listed in: + +```bash +~/.aws/credentials +``` + +Or on Windows systems: + +```bash +C:\Users\USER_NAME\.aws\credentials +``` + +If that file doesn't exist, create it, and add something like the following (assuming you have multiple AWS accounts): + +```bash +[default] +aws_access_key_id=xxx +aws_secret_access_key=xxx + +[work] +aws_access_key_id=xxx +aws_secret_access_key=xxx + +[personal] +aws_access_key_id=xxx +aws_secret_access_key=xxx +``` + +While it is recommended to explicitly declare your application's AWS profile and region in the `@aws` pragma of your project's manifest, you may also set a (default) profile and region with the `AWS_PROFILE` + `AWS_REGION` environment variables. + +--- + +### Install Architect + +The following command uses `npm`, the package manager for Node.js. + +To create an entirely new Architect project: + +
+
+
+
+
+
+
+Bash/cmd.exe
+
+
+```bash
+npm init @architect ./testapp
+```
+
+PowerShell
+
+
+```powershell
+npm init "@architect" ./testapp
+```
+
+
+
+
+
+
+
+
+Bash/cmd.exe
+
+
+```bash
+npm i -D @architect/architect
+```
+
+PowerShell
+
+
+```powershell
+npm i -D "@architect/architect"
+```
+
+
+
@@ -141,45 +143,41 @@ likes
"static": {
"fingerprint": true
},
- "ws": [
- "action",
- "connect",
- "default",
- "disconnect"
- ],
+ "ws": ["action", "connect", "default", "disconnect"],
"http": [
["get", "/"],
["get", "/likes"],
["post", "/likes"]
],
- "events": [
- "hit-counter"
- ],
+ "events": ["hit-counter"],
"scheduled": {
- "daily-affirmation": "rate(1 day)"
+ "daily-affirmation": {
+ "rate": [1, "day"]
+ }
},
"tables": {
"likes": {
- "likeID": "*String",
- "stream": true
+ "likeID": "*String"
}
},
- "indexes": {
+ "tables-streams": ["likes"],
+ "tables-indexes": {
"likes": {
"date": "*String"
}
}
}
```
+
-
-
-
-
@@ -250,28 +210,28 @@ date="*String"
Running `arc init` in the same directory as the file above generates the following Lambda function code:
-```
+```bash
.
├── src
+│ ├── events
+│ │ └── hit-counter/index.js
+│ │
│ ├── http
│ │ ├── get-index/index.js
│ │ ├── get-likes/index.js
│ │ └── post-likes/index.js
│ │
-│ ├── events
-│ │ └── hit-counter/
-│ │
│ ├── scheduled
-│ │ └── daily-affirmation/
+│ │ └── daily-affirmation/index.js
│ │
-│ ├── tables
-│ │ └── likes/
+│ ├── tables-streams
+│ │ └── likes/index.js
│ │
│ └── ws
-│ ├── action/
-│ ├── connect/
-│ ├── default/
-│ └── disconnect/
+│ ├── action/index.js
+│ ├── connect/index.js
+│ ├── default/index.js
+│ └── disconnect/index.js
│
└── app.arc
```
diff --git a/src/views/docs/en/get-started/quickstart.md b/src/views/docs/en/get-started/quickstart.md
new file mode 100644
index 00000000..77cd2d8d
--- /dev/null
+++ b/src/views/docs/en/get-started/quickstart.md
@@ -0,0 +1,60 @@
+---
+title: Quickstart
+category: Get started
+description: Get started quickly with Architect
+---
+
+> Architect is a simple framework for building and delivering powerful [Functional Web Apps (FWAs)](https://fwa.dev) on AWS
+
+## Create a new project
+
+Assuming Node.js 16+ is installed, open your terminal and create a new Architect project:
+
+
+
+
+Start the local dev server:
+
+```bash
+cd your-app
+npx arc sandbox
+```
+> `Cmd / Ctrl + c` exits the sandbox
+
+## Deploy to AWS
+
+Deploy to your built-in `staging` environment:
+
+```bash
+npx arc deploy
+```
+> Protip: create additional named development environments with the `--name` flag
+
+Ship to your built-in `production` environment:
+
+```bash
+npx arc deploy --production
+```
+
+> Be safe! Set the `ARC_APP_SECRET` environment variable in production to secure your HTTP sessions; more information in the [`env` CLI reference](../reference/cli/env)
diff --git a/src/views/docs/en/get-started/runtime-support.md b/src/views/docs/en/get-started/runtime-support.md
new file mode 100644
index 00000000..c2b94942
--- /dev/null
+++ b/src/views/docs/en/get-started/runtime-support.md
@@ -0,0 +1,71 @@
+---
+title: Architect runtime support
+category: Getting started
+description: Architect runtime support documentation
+---
+
+## Overview
+
+This document outlines the current runtime support commitments Architect makes, both for official AWS Lambda runtimes (such as Node.js), and Architect-specific runtimes (such as TypeScript and Deno).
+
+
+## Runtime support definitions
+
+### Deployment
+
+Architect will deploy your function to AWS. Caveats:
+- If you are using a compiled language, such as .NET, you may be responsible for compiling your own handlers via custom scripts or [Architect plugins](/docs/en/guides/plugins/overview); however, once compiled, [Deploy](/docs/en/reference/cli/deploy) will ship your code.
+- Some runtimes may be supported by way of an Architect runtime plugin. For example, Architect supports Rust via its [official Rust plugin](https://github.com/architect/plugin-rust).
+
+
+### Sandbox
+
+Architect's local development environment, [Sandbox](/docs/en/reference/cli/sandbox), will execute your code locally in a fully-emulated Lambda. This may also include support for automatically compiling / transpiling handlers via plugin.
+
+
+### Runtime utils
+
+Architect authors and maintains a runtime utility library, such as [`@architect/functions`](/docs/en/reference/runtime-helpers/node.js) (Node.js) or [`architect-functions`](/docs/en/reference/runtime-helpers/python) (Python), with helpers for various Architect primitives (`@http` events, etc.), service discovery support, and more.
+
+
+### Automated dependency management
+
+Architect [Deploy](/docs/en/reference/cli/deploy) (via [Hydrate](/docs/en/reference/cli/hydrate)) can be relied upon to automatically install each handler's unique dependency tree without any manual management of per-handler dependency manifests (e.g. `src/http/get-index/package.json|requirements.txt`, etc.).
+
+
+## Runtime support matrix
+
+Runtime | [Deployment][1] | [Sandbox][2] | [Runtime utils][3] | [Automated dependency management][4] |
+------------|-----------------|---------------|---------------------|---------------------------------------|
+Node.js | **✓** | **✓** | [**✓**][5] | **✓**
+TypeScript¹ | **✓** | **✓** | [**✓**][5] | **✓**
+Python | **✓** | **✓** | [**✓**][6] | **✓**
+Deno² | **✓** | **✓** | [~²][7] |
+Ruby | **✓** | **✓** | |
+Rust³ | **✓** | **✓** | |
+Go⁴ | **✓** | **✓** | |
+Java | **✓** | & | |
+.NET | **✓** | & | |
+Custom | & | & | |
+
+Legend:
+- `✓` full support
+- `~` partial support
+- `&` planned support
+
+
+¹ TypeScript supported via [official plugin](https://github.com/architect/plugin-typescript)
+
+² Deno support may not be current or stable due to ongoing issues related to [Deno compiling to AWS Linux](https://github.com/denoland/deno/issues/17925); an [in-development Deno utility library can be found here](https://github.com/architect/functions-deno)
+
+³ Rust supported via [official plugin](https://github.com/architect/plugin-rust)
+
+⁴ Go supported via [official plugin](https://github.com/architect/plugin-go)
+
+[1]: #deployment
+[2]: #sandbox
+[3]: #runtime-utils
+[4]: #automated-dependency-management
+[5]: /docs/en/reference/runtime-helpers/node.js
+[6]: /docs/en/reference/runtime-helpers/python
+[7]: /docs/en/reference/runtime-helpers/deno
diff --git a/src/views/docs/en/guides/get-started/why-architect.md b/src/views/docs/en/get-started/why-architect.md
similarity index 73%
rename from src/views/docs/en/guides/get-started/why-architect.md
rename to src/views/docs/en/get-started/why-architect.md
index 428699c9..36107e16 100644
--- a/src/views/docs/en/guides/get-started/why-architect.md
+++ b/src/views/docs/en/get-started/why-architect.md
@@ -4,11 +4,13 @@ category: Get started
description: Why is Architect important to you?
---
-> Architect provides everything you need to build massively scalable serverless apps with low code, clear and terse config, and zero ceremony
+> Architect provides everything you need to build massively scalable [Functional Web Apps (FWAs)](https://fwa.dev) with low code, clear and terse config, and zero ceremony
+
## The best developer experience
-Going serverless is fraught with complex vendor arcana and market noise. This is where Architect comes in. Architect is an opinionated developer experience (DX) for building database backed web apps with AWS. We remove all the noise and friction to building serverlessly. We prioritize speed with fast local dev, smart configurable defaults and flexible Infrastructure as Code. And then we get out of your way so you can focus on business logic instead of glue code and only pay for services while in use, on-demand, and otherwise _scale to zero_.
+Building a functional web app can be fraught with complex vendor arcana and market noise. This is where Architect comes in. Architect is an opinionated developer experience (DX) for building database backed web apps with AWS. We remove all the noise and friction to building FWAs. We prioritize speed with fast local dev, smart configurable defaults and flexible Infrastructure as Code. And then we get out of your way so you can focus on business logic instead of glue code and only pay for services while in use, on-demand, and otherwise _scale to zero_.
+
### Work locally
@@ -16,7 +18,7 @@ Developers need to work locally, to debug, test, and preview code before deployi
### Infrastructure as Code
-At its heart Architect is an [Infrastructure as Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) (IaC) framework. Architect defines a high level manifest file, in multiple open text formats, and turns formerly complex cloud infrastructure provisioning into a build artifact. You define the cloud infrastructure your application code requires and check that manifest into version control so infra and code are always aligned and deterministic. Architect compiles manifest code into AWS CloudFormation and deploys it. Architect supports a native text file format `app.arc` in addition to popular formats: `package.json`, `arc.json`, `arc.yaml` and `arc.toml`. Teams can choose the dialect that works best for them.
+At its heart Architect is an [Infrastructure as Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) (IaC) framework. Architect defines a high level manifest file, in multiple open text formats, and turns formerly complex cloud infrastructure provisioning into a build artifact. You define the cloud infrastructure your application code requires and check that manifest into version control so infra and code are always aligned and deterministic. Architect compiles manifest code into AWS CloudFormation and deploys it. Architect supports a native text file format `app.arc` in addition to popular formats: `package.json`, `arc.json`, and `arc.yaml`. Teams can choose the dialect that works best for them.
### Secured to least privilege by default
diff --git a/src/views/docs/en/guides/backend/begin-data-backup.md b/src/views/docs/en/guides/backend/begin-data-backup.md
new file mode 100644
index 00000000..c618b386
--- /dev/null
+++ b/src/views/docs/en/guides/backend/begin-data-backup.md
@@ -0,0 +1,142 @@
+---
+title: Download a Begin environment's data
+description:
+---
+
+Begin was a common means of deploying Architect apps, and a long-time sponsor of the Architect project. Prior to the shutdown of Begin, customers can download their environment data for use in Architect apps like so:
+
+
+## Usage
+
+Node.js 20.x+ is required.
+
+Use this script to download a Begin app environment's data. Either a single table (recommended) or all tables.
+
+First, create a script file:
+
+```bash
+touch ./begin-download.mjs
+```
+
+Then paste in the [script contents below](#download-script).
+
+This program will use your stored Begin credentials, and ask for an `appID`, `envID`, and the name of your table.
+A `.json` file will be saved to disk alongside the `begin-download.mjs` file:
+
+```javascript
+// data-appID-envID-tables.json
+[
+ {
+ name: String,
+ info: DynamoDB.TableDescription,
+ items: [DynamoDB.Item],
+ complete: Boolean, // true, if the entire table was downloaded
+ }
+]
+```
+
+When ready, run it like so:
+
+```bash
+node begin-download.mjs
+```
+
+
+## 100MB Limit
+
+If the requested table (or all tables when no table name is specified) exceeds 100MB, partial data will be returned.
+If you encounter this, you can request a custom export via [Discord](https://discord.com/invite/y5A2eTsCRX) or support@begin.com.
+
+## Notes
+
+Retrieve app and env IDs with the Begin CLI:
+
+```bash
+begin list
+# or, if the CLI isn't installed:
+npx @begin/deploy@latest list
+```
+
+Refer to your application's `*.arc` file for a list of table names.
+
+---
+
+## Download script
+
+```javascript
+// begin-download.mjs
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import readline from 'node:readline'
+import url from 'node:url'
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+const currentDir = path.dirname(url.fileURLToPath(import.meta.url))
+const homeDir = process.env.HOME || process.env.USERPROFILE || '~'
+const configPath = path.join(homeDir, '.begin', 'config.json')
+
+function question (query) {
+ return new Promise((resolve) => rl.question(query, resolve))
+}
+
+async function main() {
+ let TOKEN
+ try {
+ const config = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+ TOKEN = config.access_token
+ if (!TOKEN) throw 'access_token not found in Begin config'
+ } catch (error) {
+ TOKEN = question('Enter Begin API access token: ')
+ }
+ if (!TOKEN) throw 'Begin API token required!'
+
+ const APP_ID = await question('Enter appID: ')
+ if (APP_ID.length < 8) throw 'appID required'
+ const ENV_ID = await question('Enter envID: ')
+ if (ENV_ID.length < 8) throw 'envID required'
+ const TABLE = await question('Enter table name (optional, press Enter to skip): ')
+
+ let URL = 'https://api.begin.com/v1'
+ URL += `/apps/${APP_ID}/${ENV_ID}/data`
+ if (TABLE) URL += `?table=${TABLE}`
+
+ const response = await fetch(
+ URL,
+ {
+ headers: {
+ authorization: `bearer ${TOKEN}`,
+ 'content-type': 'application/json',
+ },
+ }
+ )
+
+ if (!response.ok) throw `ERROR: ${await response.text()}`
+
+ const tables = await response.json()
+
+ if (!tables || tables.length === 0) throw 'No data returned'
+
+ let filename = `data-${APP_ID}-${ENV_ID}-${TABLE ? `${TABLE}` : 'tables'}.json`
+ fs.writeFileSync(
+ path.join(currentDir, filename),
+ JSON.stringify(tables, null, 2),
+ )
+
+ for (const { info, name, items, complete } of tables) {
+ console.log(`\nTable "${name}"`)
+ if (!complete) console.log('Incomplete scan! Table too large.')
+ console.log(` <${info.TableId}>`)
+ console.log(` (${items.length} items)`)
+ }
+
+ console.log(`\nSaved ./${filename}`)
+
+ rl.close()
+}
+
+main().catch((e) => {
+ console.error(e)
+ process.exit(1)
+})
+```
diff --git a/src/views/docs/en/guides/backend/database-functions.md b/src/views/docs/en/guides/backend/database-functions.md
index 07922839..bfd4b80a 100644
--- a/src/views/docs/en/guides/backend/database-functions.md
+++ b/src/views/docs/en/guides/backend/database-functions.md
@@ -11,7 +11,7 @@ sections:
Architect database functions are a log of information about changes to items in a DynamoDB table. When you enable a stream on a table under the `@tables` pragma in your `app.arc` file, DynamoDB captures information about every modification to data items in the table.
-This functionality is commonly used to stream data to other sources and provide data-based event triggers. (eg. when I add new user row to the accounts table …send a welcome email)
+This functionality is commonly used to stream data to other sources and provide data-based event triggers. (e.g. when I add new user row to the accounts table …send a welcome email)
Database functions capture a time-ordered sequence of item-level modifications in any DynamoDB table and stores this information in a log for up to 24 hours. Applications can access this log and view the data items as they appeared before and after they were modified, in near-real-time.
diff --git a/src/views/docs/en/guides/backend/event-functions.md b/src/views/docs/en/guides/backend/event-functions.md
index 0826a339..4e309c5a 100644
--- a/src/views/docs/en/guides/backend/event-functions.md
+++ b/src/views/docs/en/guides/backend/event-functions.md
@@ -36,13 +36,14 @@ account-signup
account-check-email
```
-### `@events` Syntax
+### `@events` syntax
-- Lowercase alphanumeric string
-- Maximum of 50 characters
-- Dashes are allowed; underscores are not allowed
+- Lower + upper case alphanumeric string
+- Maximum of 240 characters
+- Dashes, periods, and underscores are allowed
- Must begin with a letter
+
### Provisioning new event functions
To provision a new event function, in the root of your project, open your app's Architect project manifest file (usually `app.arc`):
@@ -76,7 +77,7 @@ Additionally `AWS::SSM::Parameter` resources are created for every SNS Topic whi
- **`/[StackName]/events/[EventName]`** with a value of the generated SNS Topic ARN
-> All runtime functions have the environment variable `AWS_CLOUDFORMATION` which is the currently deployed CloudFormation stack name; this combined w the runtime `aws-sdk` or `@architect/functions` can be used to lookup these values in SSM
+> All runtime functions have the environment variables `ARC_APP_NAME` and `ARC_STACK_NAME` which is the currently deployed CloudFormation stack name; this can be used by [`aws-lite`](https://aws-lite.org), `aws-sdk`, and `@architect/functions` to look up these values in SSM
---
@@ -172,4 +173,3 @@ function count(payload, callback) {
exports.handler = arc.events.subscribe(count)
```
-
diff --git a/src/views/docs/en/guides/backend/events-and-queues.md b/src/views/docs/en/guides/backend/events-and-queues.md
index 11544016..e3dc2aca 100644
--- a/src/views/docs/en/guides/backend/events-and-queues.md
+++ b/src/views/docs/en/guides/backend/events-and-queues.md
@@ -11,7 +11,7 @@ sections:
## Overview
-Background tasks are a common workload and perfect for serverless environments. They reinforce event-driven architecture and allow you to perform asynchronous work across a distributed system. These functions are well suited for processes that don't require an immediate response, or are too resource intensive for a single function.
+Background tasks are a common workload and perfect for [Functional Web Apps](https://fwa.dev). They reinforce event-driven architecture and allow you to perform asynchronous work across a distributed system. These functions are well suited for processes that don't require an immediate response, or are too resource intensive for a single function.
Architect has three main primitives of background functions:
- [@events](/docs/en/reference/arc-pragmas/@events) - A pub/sub service that uses SNS.
@@ -34,10 +34,32 @@ In this tutorial, we will create an event topic, POST JSON data to invoke a subs
1. We will start with a fresh project and install dependencies.
-``` bash
-npm init @architect ./arc-event-app
+
+
+
2. Open up your `app.arc` file and add the `@event` pragma along with a POST route
```arc
@@ -121,7 +143,7 @@ async function yolo() {
return { location: '/' }
}
-exports.handler = arc.http.async(yolo)
+exports.handler = arc.http(yolo)
```
Test it locally by running `npm start` in your terminal from the project root. Architect's Sandbox environment will emulate the same behavior once your project is deployed. Within the event function, you can split logic among code from `src/shared`.
@@ -137,10 +159,31 @@ Another common background task is `@scheduled` functions. These functions are in
The first thing we will need is a fresh Architect project. We can create one directly from the terminal.
+
+
Now we can open up the `app.arc` file and add a scheduled function to the manifest.
@@ -183,7 +226,7 @@ From the terminal, run `arc deploy --dry-run` and take a look at `sam.yaml` in t
"Properties": {
"Handler": "index.handler",
"CodeUri": "./src/scheduled/daily",
- "Runtime": "nodejs12.x",
+ "Runtime": "nodejs14.x",
"MemorySize": 1152,
"Timeout": 5,
"Environment": {
@@ -196,7 +239,7 @@ From the terminal, run `arc deploy --dry-run` and take a look at `sam.yaml` in t
},
"ARC_APP_NAME": "arc-scheduled-app",
"ARC_HTTP": "aws_proxy",
- "NODE_ENV": "staging",
+ "ARC_ENV": "staging",
"SESSION_TABLE_NAME": "jwe"
}
},
@@ -231,10 +274,31 @@ The `Events` property on the `Daily` function shows that this is a scheduled eve
Let's make an example message queue by starting with a fresh Architect project.
+
+
Open up the `app.arc` file and modify the manifest to include our `@queues` function as follows:
diff --git a/src/views/docs/en/guides/backend/persist-data.md b/src/views/docs/en/guides/backend/persist-data.md
index c73a0a92..8071d051 100644
--- a/src/views/docs/en/guides/backend/persist-data.md
+++ b/src/views/docs/en/guides/backend/persist-data.md
@@ -24,6 +24,7 @@ In this tutorial you will build a simple note taking application, with multiple
**Sections**
+- [Overview](#overview)
- [Generating the Data Layer](#generating-the-data-layer)
- [Implementing an Admin Interface](#implementing-an-admin-interface)
- [Implementing Signup](#implementing-signup)
@@ -99,13 +100,13 @@ touch src/shared/layout.js
// src/shared/layout.js
let arc = require('@architect/functions'),
- url = arc.http.helpers.url,
- static = arc.http.helpers.static
+ url = arc.http.helpers.url,
+ static = arc.http.helpers.static
module.exports = function layout(contents, showNav = true, isLoggedIn = true) {
- var nav = ''
+ let nav = ''
- var navLinks = `
+ let navLinks = `
Log in
Sign up
`
@@ -132,9 +133,7 @@ module.exports = function layout(contents, showNav = true, isLoggedIn = true) {
Architect demo app
-
-
-
+
${ nav }
@@ -154,8 +153,8 @@ Next, we require the layout module in the root of our application. This will sho
// src/http/get-index/index.js
let arc = require('@architect/functions'),
- layout = require('@architect/shared/layout'),
- url = arc.http.helpers.url
+ layout = require('@architect/shared/layout'),
+ url = arc.http.helpers.url
require('@architect/shared/globals')
@@ -165,7 +164,7 @@ exports.handler = async function http(request) {
let isLoggedIn = !!state.person
- var loggedInPage = `
+ let loggedInPage = `
`
- var notLoggedInPage = `
+ let notLoggedInPage = `
arc
@@ -122,12 +121,15 @@ daily-affirmation rate(1 day)
@tables
likes
likeID *String
- stream true
-@indexes
+@tables-streams
+likes
+
+@tables-indexes
likes
date *String
```
+
yaml
```yaml
+---
app: "hello"
static:
fingerprint: true
@@ -197,51 +195,13 @@ events:
scheduled:
- daily-affirmation: "rate(1 day)"
tables:
- - likes: {likeID: "*String", stream: true}
-indexes:
- - likes: {date: "*String"}
+ - likes: { likeID: "*String" }
+tables-streams:
+ - likes
+tables-indexes:
+ - likes: { date: "*String" }
```
-
-toml
-
-
-```toml
-app="hello"
-[static]
-fingerprint=true
-
-ws=[
- "action",
- "connect",
- "default",
- "disconnect"
-]
-
-http=[
- ["get", "/"],
- ["get", "/likes"],
- ["post", "/likes"],
-]
-
-events=["hit-counter"]
-
-[scheduled]
-daily-affirmation=["rate(1 day)"]
-
-[[tables]]
-
-[tables.likes]
-likeiD="*String"
-stream=true
-
-[[indexes]]
-[indexes.likes]
-date="*String"
-```
+
+
+
+
+
+
+Bash/cmd.exe
+
+
+```bash
+npm init @architect your-app
+```
+
+PowerShell
+
+
+```powershell
+npm init "@architect" your-app
+```
+
+
+
+
+
+
+
+
+Bash/cmd.exe
+
+
+```bash
+npm init @architect arc-event-app
cd arc-event-app
```
+
+PowerShell
+
+
+```powershell
+npm init "@architect" arc-event-app
+cd arc-event-app
+```
+
+
+
+
+
+
+
+
+Bash/cmd.exe
+
+
```bash
npm init @architect ./arc-scheduled-app
cd arc-scheduled-app
```
+
+PowerShell
+
+
+```powershell
+npm init "@architect" ./arc-scheduled-app
+cd arc-scheduled-app
+```
+
+
+
+
+
+
+
+
+Bash/cmd.exe
+
+
```bash
npm init @architect ./arc-queues-app
cd arc-queues-app
```
+
+PowerShell
+
+
+```powershell
+npm init "@architect" ./arc-queues-app
+cd arc-queues-app
+```
+
+