From 39a992d2e89f807292d58bbe36acb3da9910da80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Eriksson?= Date: Tue, 2 May 2023 17:30:32 +0200 Subject: [PATCH] docs: add pubsub outbox, sync docs --- docs/community/contribute.md | 6 +- docs/community/open-source.md | 8 +- docs/deploy/custom-domains.md | 2 +- docs/deploy/environments.md | 4 +- docs/deploy/infra.md | 32 ++--- docs/deploy/own-cloud.md | 11 +- docs/deploy/security.md | 3 +- docs/develop/api-docs.md | 4 +- docs/develop/api-schemas.md | 4 +- docs/develop/auth.md | 6 +- docs/develop/config.md | 4 + docs/develop/errors.md | 4 + docs/develop/metadata.md | 4 + docs/develop/middleware.md | 4 + docs/develop/testing.md | 4 + docs/docs.cue | 5 +- docs/encore-way.md | 2 +- docs/how-to/connect-existing-db.md | 2 +- docs/how-to/migrate-away.md | 62 +++++----- docs/how-to/migrate-to-encore.md | 6 +- docs/index.mdx | 13 +- docs/install.md | 2 +- docs/introduction.md | 111 +++++++---------- docs/menu.json | 12 ++ docs/observability/dev-dash.md | 20 ++- docs/observability/encore-flow.md | 2 +- docs/observability/logging.md | 4 + docs/observability/metrics.md | 73 ++++++----- docs/observability/tracing.md | 2 +- docs/other/vs-heroku.md | 6 +- docs/other/vs-supabase.md | 4 +- docs/other/vs-terraform.md | 2 +- docs/primitives/caching.md | 4 + docs/primitives/code-snippets.md | 4 +- docs/primitives/cron-jobs.md | 15 ++- docs/primitives/databases.md | 38 +++--- docs/primitives/overview.md | 49 +++----- docs/primitives/pubsub-outbox.md | 123 +++++++++++++++++++ docs/primitives/pubsub.md | 120 +++++++++--------- docs/primitives/secrets.md | 66 +++++----- docs/quick-start.mdx | 87 ++++++------- docs/tutorials/create-app.md | 2 +- docs/tutorials/incident-management-tool.md | 11 +- docs/tutorials/index.md | 73 +++++++---- docs/tutorials/{rest-api.md => rest-api.mdx} | 12 +- docs/tutorials/slack-bot.md | 7 +- docs/tutorials/sql-database.md | 3 +- docs/tutorials/uptime.md | 3 + 48 files changed, 602 insertions(+), 443 deletions(-) create mode 100644 docs/primitives/pubsub-outbox.md rename docs/tutorials/{rest-api.md => rest-api.mdx} (96%) diff --git a/docs/community/contribute.md b/docs/community/contribute.md index 0814bdde3a..8641f5c825 100644 --- a/docs/community/contribute.md +++ b/docs/community/contribute.md @@ -1,15 +1,15 @@ --- seotitle: How to contribute to Encore Open Source Project -seodesc: Learn how to contribute to Encore's Open Source project by submitting pull requests, reporting bugs, or contributing documentation or example projects. +seodesc: Learn how to contribute to the Encore Open Source project by submitting pull requests, reporting bugs, or contributing documentation or example projects. title: Ways to contribute subtitle: Guidelines for contributing to Encore --- We’re so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. -### Open Source Framework +### Open Source Project -If you want to contribute to the Encore framework Open Source project, you can submit a pull request on [GitHub](https://github.com/encoredev/encore/pulls). +If you want to contribute to the Encore Open Source project, you can submit a pull request on [GitHub](https://github.com/encoredev/encore/pulls). ### Report issues diff --git a/docs/community/open-source.md b/docs/community/open-source.md index 919689b837..d2839ecc2d 100644 --- a/docs/community/open-source.md +++ b/docs/community/open-source.md @@ -1,15 +1,15 @@ --- seotitle: Encore is Open Source -seodesc: We believe Open Source is key to a sustainable and prosperous technology community. The Encore framework builds on Open Source software, and is itself Open Source. +seodesc: We believe Open Source is key to a sustainable and prosperous technology community. Encore builds on Open Source software, and is itself Open Source. title: Open Source subtitle: Encore is Open Source Software --- -We believe Open Source is key to a long-term sustainable and prosperous technology community. The Encore framework builds on Open Source software, and is itself Open Source. This means the Encore framework is free to use and open to contributions. +We believe Open Source is key to a long-term sustainable and prosperous technology community. Encore builds on Open Source software, and is largely Open Source itself. ## License -The Encore framework is Open Source under Mozilla Public License 2.0. +The Encore infrastructure SDK, parser, and compiler are Open Source under Mozilla Public License 2.0. > The MPL is a simple copyleft license. The MPL's "file-level" copyleft is designed to encourage contributors to share modifications they make to your code, while still allowing them to combine your code with code under other licenses (open or proprietary) with minimal restrictions. @@ -17,4 +17,4 @@ You can learn more about MPL 2.0 on [the official website](https://www.mozilla. ## Contribute -Contributions to improve the Encore framework are very welcome. Contribute to Encore on [GitHub](https://github.com/encoredev/encore). +Contributions to improve Encore are very welcome. Contribute to Encore on [GitHub](https://github.com/encoredev/encore). diff --git a/docs/deploy/custom-domains.md b/docs/deploy/custom-domains.md index 2e15a56aad..fc9512c1ac 100644 --- a/docs/deploy/custom-domains.md +++ b/docs/deploy/custom-domains.md @@ -48,7 +48,7 @@ On the Custom Domains settings page, you can see the various statuses throughout | Status | Description | | - | - | -| `Pending` | The domain is currently queued to be provisioned by the Encore platform. | +| `Pending` | The domain is currently queued to be provisioned by Encore. | |`Waiting for CNAME` | Encore is waiting for the CNAME to become active and for the SSL certificate to be issued for the domain. | | `Configuring Edge Routers` | The SSL certificate has been issued and the Encore edge routers are being configured to route traffic on the domain. | | `Active` | The domain is serving traffic to your Encore application. | diff --git a/docs/deploy/environments.md b/docs/deploy/environments.md index 5842119465..da80cf7174 100644 --- a/docs/deploy/environments.md +++ b/docs/deploy/environments.md @@ -12,7 +12,7 @@ Environments always stay in sync, as they are created based on the needs of your ## Creating environments -To create an environment for your app, open your app in the [Encore web platform](https://app.encore.dev) and go to the **Environments** page, +To create an environment for your app, open your app in the [Cloud Dashboard](https://app.encore.dev) and go to the **Environments** page, then click on `Create env` in the top right. There you can pick a name, and decide if you want a production @@ -54,7 +54,7 @@ When you [connect your application to GitHub](/docs/how-to/github), Encore will Preview Environments are named after the pull request, for example PR #72 creates a preview environment named `pr:72` with the API base url `https://pr72-$APP_ID.encr.app`. -You can also view the environment in the web platform, where the url will be `https://app.encore.dev/$APP_ID/envs/pr:72`. +You can also view the environment in the Cloud Dashboard, where the url will be `https://app.encore.dev/$APP_ID/envs/pr:72`. See the [infra docs](/docs/deploy/infra#preview-environments) if you're curious about exactly how Preview Environments are provisioned. diff --git a/docs/deploy/infra.md b/docs/deploy/infra.md index 5ebcbba96b..734d3645d6 100644 --- a/docs/deploy/infra.md +++ b/docs/deploy/infra.md @@ -5,21 +5,23 @@ title: Infrastructure provisioning subtitle: How Encore provisions infrastructure for your application --- -Encore automatically provisions all necessary infrastructure, in all environments and across all major cloud providers, without requiring any application code changes. All you need to do is [connect your cloud account](./own-cloud) and create an environment. +Encore automatically provisions all necessary infrastructure, in all environments and across all major cloud providers, without requiring application code changes. You simply [connect your cloud account](./own-cloud) and create an environment. - + -This is powered by the Encore framework. It lets you write regular Go code, and use infrastructure primitives (databases, caches, queues, and scheduled jobs) directly in application code through cloud-agnostic APIs. +This is powered by Encore's [Infrastructure SDK](/docs/primitives/overview), which lets you write regular Go code and declare infrastructure resources (databases, caches, queues, and scheduled jobs) in application code. -This completely removes the need for infrastructure configuration files, and avoids creating cloud-specific dependencies in your application. +At compile time, Encore creates an [Application Model](/docs/introduction#meet-the-encore-application-model) with a definition of the infrastructure your application requires. Encore then uses this model to provision the infrastructure in both your cloud account, and development and preview environments in Encore Cloud. -At compile time, Encore creates an [Application Model](/docs/introduction#meet-the-encore-application-model) containing a precise definition of the infrastructure your application requires. The Encore Platform uses this model to provision necessary infrastructure in your own cloud account, and development and preview environments in Encore Cloud. +The approach removes the need for infrastructure configuration files and avoids creating cloud-specific dependencies in your application. -This end-to-end integration between application code and infrastructure enables Encore to always keep your environments in sync. +Having an end-to-end integration between application code and infrastructure also enables Encore to keep environments in sync and track cloud infrastructure, giving you an up-to-date view of your infrastructure to avoid unnecessary cloud costs. + + ## Environment types -Encore provisions every type of environment, and ensures they stay in sync. +By default, Encore provisions infrastructure using contextually appropriate objectives for each environment type. You retain control and configurability of infrastructure in your cloud account, and can access settings via your cloud provider as if you set up the infrastructure manually. | | Local | Encore Cloud | GCP / AWS / Azure | | - | - | - | - | - | - | @@ -78,11 +80,11 @@ Encore provisions production infrastructure resources using best-practice guidel | | GCP | AWS | Azure | | - | - | - | - | -| **Networking:** | [VPC][gcp-vpc] | [VPC][aws-vpc] | [VPC][azure-vpc] | -| **Compute:** | [Cloud Run][gcp-cloudrun] | [Fargate ECS][aws-fargate] | [App Service][azure-app-service] & [App Service Plan][azure-app-service-plan] | -| **SQL Databases:** | [GCP Cloud SQL][gcp-cloudsql] | [Amazon RDS][aws-rds] | [Azure Database][azure-sqldb] | -| **Pub/Sub:** | [GCP Pub/Sub][gcp-pubsub] | [Amazon SQS][aws-sqs] & [Amazon SNS][aws-sns] | [Azure Service Bus][azure-service-bus] | -| **Caches:** | [GCP Memorystore (Redis)][gcp-redis] | [Amazon ElastiCache (Redis)][aws-redis] | [Azure Cache (Redis)][azure-redis] | +| **Networking:** | [VPC](#google-cloud-platform-gcp) | [VPC](#amazon-web-services-aws) | [VPC](#microsoft-azure) | +| **Compute:** | [Cloud Run](#google-cloud-platform-gcp) | [Fargate ECS](#amazon-web-services-aws) | [App Service](#microsoft-azure) & [App Service Plan](#microsoft-azure) | +| **SQL Databases:** | [GCP Cloud SQL](#sql-databases) | [Amazon RDS](#sql-databases-1) | [Azure Database](#sql-databases-2) | +| **Pub/Sub:** | [GCP Pub/Sub](#pubsub) | [Amazon SQS][aws-sqs] & [Amazon SNS](#pubsub-1) | [Azure Service Bus](pubsub-2) | +| **Caches:** | [GCP Memorystore (Redis)](#caching) | [Amazon ElastiCache (Redis)](#caching-1) | [Azure Cache (Redis)](#caching-2) | | **Cron Jobs:** | [Encore Managed][encore-cron] | [Encore Managed][encore-cron] | [Encore Managed][encore-cron] | | **Secrets:** | [Secret Manager][gcp-secrets] | [AWS Secrets Manager][aws-secrets] | [App Service App][azure-app-service-secrets] | @@ -131,7 +133,7 @@ Additionally, Encore sets up: * A 10% memory buffer to better memory fragmentation, and active defragmentation #### Cron Jobs -When using [Cron Jobs][encore-cron], Encore's Cloud Platform triggers the execution +When using [Cron Jobs][encore-cron], Encore Cloud triggers the execution of cron jobs by calling the corresponding API using a signed request so the application can verify the source of the request as coming from Encore's cron functionality. No infrastructure is provisioned for this to work. @@ -181,7 +183,7 @@ Additionally, Encore sets up: * A 10% memory buffer to better memory fragmentation, and active defragmentation #### Cron Jobs -When using [Cron Jobs][encore-cron], Encore's Cloud Platform triggers the execution +When using [Cron Jobs][encore-cron], Encore Cloud triggers the execution of cron jobs by calling the corresponding API using a signed request so the application can verify the source of the request as coming from Encore's cron functionality. No infrastructure is provisioned for this to work. @@ -231,7 +233,7 @@ Additionally, Encore sets up: * An [Azure Private Link][azure-private-link] connection for secure connectivity from the VPC #### Cron Jobs -When using [Cron Jobs][encore-cron], Encore's Cloud Platform triggers the execution +When using [Cron Jobs][encore-cron], Encore Cloud triggers the execution of cron jobs by calling the corresponding API using a signed request so the application can verify the source of the request as coming from Encore's cron functionality. No infrastructure is provisioned for this to work. diff --git a/docs/deploy/own-cloud.md b/docs/deploy/own-cloud.md index c5b5351d0a..e3047fdc83 100644 --- a/docs/deploy/own-cloud.md +++ b/docs/deploy/own-cloud.md @@ -24,15 +24,14 @@ within Encore, you need to manually remove the infrastructure that was created b Encore provides a GCP Service Account for each Encore application, letting you grant Encore access to provision all the necessary infrastructure directly in your own GCP Organization account. -To find your app's Service Account email and configure GCP deployments, head over to the Cloud Deploy page by going to -**[the Encore web platform](https://app.encore.dev/) > (Select your app) > App Settings > Integrations > Cloud Deploy**. +To find your app's Service Account email and configure GCP deployments, head over to the Connect Cloud page by going to Encore's **[Cloud Dashboard](https://app.encore.dev/) > (Select your app) > App Settings > Integrations > Connect Cloud**. ![Connect GCP account](/assets/docs/connectgcp.png "Connect GCP account") ## Amazon Web Services (AWS) -To configure your Encore app to deploy to your AWS account, head over to the Cloud Deploy page by going to -**[the Encore web platform](https://app.encore.dev/) > (Select your app) > App Settings > Integrations > Cloud Deploy**. +To configure your Encore app to deploy to your AWS account, head over to the Connect Cloud page by going to Encore's +**[Cloud Dashboard](https://app.encore.dev/) > (Select your app) > App Settings > Integrations > Connect Cloud**. Follow the instructions to create an IAM Role, and then connect the role with Encore. [Learn more in the AWS docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html). @@ -51,8 +50,8 @@ After connecting your app to AWS, you will be asked to choose which region you w ## Microsoft Azure -To configure for Azure deployments, head over to the Cloud Deploy page by going to -**[the Encore web platform](https://app.encore.dev/) > (Select your app) > App Settings > Integrations > Cloud Deploy**. +To configure for Azure deployments, head over to the Connect Cloud page by going to Encore's +**[Cloud Dashboard](https://app.encore.dev/) > (Select your app) > App Settings > Integrations > Connect Cloud**. Start by filling in your Azure Tenant ID, then click on **Connect app to Azure**. This will redirect you to Microsoft's Azure portal requesting that you grant permission for diff --git a/docs/deploy/security.md b/docs/deploy/security.md index b6a5a23ec0..098c308838 100644 --- a/docs/deploy/security.md +++ b/docs/deploy/security.md @@ -7,8 +7,7 @@ subtitle: Keeping your application secure by default Encore's security practices are informed by our team's decades-long experience working with payments, and other sensitive systems, at Spotify, Google, and Monzo. -This expertise has also been used when designing the Encore framework, ensuring that building secure applications -is more convenient than building insecure ones. +This expertise has also been used when designing the Encore infrastructure SDK, ensuring that building secure applications is more convenient than building insecure ones. For example, Encore's [secrets management](/docs/primitives/secrets) gives you an incredibly simple way of using secret keys, while at the same time providing diff --git a/docs/develop/api-docs.md b/docs/develop/api-docs.md index 39f6eacdd6..134bae713d 100644 --- a/docs/develop/api-docs.md +++ b/docs/develop/api-docs.md @@ -11,7 +11,7 @@ But the effort of maintaining inevitably leads to them becoming stale and out of Encore provides the best of both worlds — great API docs that never become out of date — by leveraging the [Encore Application Model](/docs/introduction#meet-the-encore-application-model) to determine the structure of every API. -The API docs are available to your whole team via [the Encore platform](https://app.encore.dev). +The API docs are available to your whole team via the [Cloud Dashboard](https://app.encore.dev).