![\"encore](\"https://user-images.githubusercontent.com/78424526/214602214-52e0483a-b5fc-4d4c-b03e-0b7b23e012df.svg\")
![](\"/assets/docs/initllm.png\")
\n\n**Existing projects:** Run `encore llm-rules init` to add AI support:\n\n```bash\nencore llm-rules init\n```\n\nThis prompts you to select a tool and generates the appropriate configuration file (`.cursorrules`, `CLAUDE.md`, etc.).\n\nBoth commands also set up MCP server configuration for tools that support it (Cursor, Claude Code). If you want to set up MCP manually, see [MCP Server](#mcp-server) below.\n\nSupported tools: Cursor, Claude Code, VS Code, AGENTS.md, and Zed.\n\n### Method 2: Using Encore Skills\n\nUse the [Encore skills package](https://github.com/encoredev/skills) which works with Cursor, Claude Code, GitHub Copilot, and 10+ other AI agents:\n\n```bash\nnpx add-skill encoredev/skills\n```\n\nYou can also install specific skills or target specific agents:\n\n```bash\n# List available skills\nnpx add-skill encoredev/skills --list\n\n# Install to specific agents\nnpx add-skill encoredev/skills -a cursor -a claude-code\n```\n\nThe skills package includes a migration skill that can automatically migrate your existing backend to Encore Go. See the [Migrate using AI agent](/docs/go/migration/ai-migration) guide to learn more.\n\n## MCP Server\n\nEncore's [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server gives AI agents deep introspection into your application: querying databases, calling APIs, inspecting services, and analyzing traces.\n\n### Start the Server\n\nFrom your Encore app directory:\n\n```bash\nencore mcp start\n```\n\nThis displays connection information. Keep it running while using your AI tools.\n\n### Connect Cursor\n\n**Quick setup:** Use this button (update `your-app-id` to your actual app ID):\n\n![\"Add](\"https://cursor.com/deeplink/mcp-install-dark.svg\")
![](\"/assets/docs/flow-diagram.png\" "\\"Encore")
\n\n## Standardization brings clarity\n\nDevelopers make dozens of decisions when creating a backend application. Deciding how to structure the codebase, defining API schemas, picking underlying infrastructure, etc. The decisions often come down to personal preferences, not technical rationale. This creates a huge problem in the form of fragmentation! When every stack looks different, all tools have to be general purpose.\n\nWhen you adopt Encore, many of these stylistic decisions are already made for you. The Encore framework ensures your application follows modern best practices. And when you run your application, Encore's Open Source parser and compiler check that you're sticking to the standard. This means you're free to focus your energy on what matters: writing your application's business logic."
},
{
"path": "docs/go/concepts/benefits.md",
"content": "---\nseotitle: Benefits of using Encore.go\nseodesc: See how Encore.go helps you build backends faster using Go.\ntitle: Encore.go Benefits\nsubtitle: How Encore.go helps you build robust distributed systems, faster.\nlang: go\n---\n\nUsing Encore.go to declare infrastructure in application code helps unlock several benefits:\n\n- **Local development with instant infrastructure**: Encore.go automatically sets up necessary infrastructure as you develop.\n- **Rapid feedback**: Catch issues early with type-safe infrastructure, avoiding slow deployment cycles.\n- **No manual configuration required**: No need for Infrastructure-as-Code. Your code is the single source of truth.\n- **Unified codebase**: One codebase for all environments; local, preview, and cloud.\n- **Cloud-agnostic by default**: Encore.go provides an abstraction layer on top of the cloud provider's APIs, so you avoid becoming locked in to a single cloud.\n- **Evolve infrastructure without code changes**: As requirements evolve, you can change the provisioned infrastructure without making code changes, you only need to change the infrastructure configuration which is separate from the application code.\n- **AI-assisted development**: Encore is built for AI coding assistants. With [Encore-specific rules and MCP integration](/docs/go/ai-integration), AI understands your architecture and can generate type-safe, pattern-consistent code and introspect your app—services, APIs, databases, and traces.\n\n## No DevOps experience required\n\nEncore provides open source tools to help you integrate with your cloud infrastructure, enabling you to self-host your application anywhere that supports Docker containers.\nLearn more in the [self-host documentation](/docs/go/self-host/docker-build).\n\nYou can also use [Encore Cloud](https://encore.dev/use-cases/devops-automation), which fully automates provisioning and managing infrastructure in your own cloud on AWS and GCP.\n\nThis approach dramatically reduces the level of DevOps expertise required to use scalable, production-ready, cloud services like Kubernetes and Pub/Sub. And because your application code is the source of truth for infrastructure requirements, it ensures the infrastructure in all your environments are always in sync with the application's requirements.\n\n## Simplicity without giving up flexibility\n\nEncore.go provides integrations for common infrastructure primitives, but also allows for flexibility. You can always use any cloud infrastructure, even if it's not built into Encore.go. If you use Encore's [Cloud Platform](https://encore.dev/use-cases/devops-automation), it [automates infrastructure](/docs/platform/infrastructure/infra) using your own cloud account, so you always have full access to your services from the cloud provider's console.\n"
},
{
"path": "docs/go/develop/api-docs.md",
"content": "---\nseotitle: Service Catalog & Generated API Docs\nseodesc: See how Encore automatically generates API documentation that always stays up to date and in sync.\ntitle: Service Catalog\nsubtitle: Automatically get a Service Catalog and complete API docs\n---\n\nAll developers agree API documentation is great to have, but the effort of maintaining it inevitably leads to docs becoming stale and out of date.\n\nTo solve this, Encore uses the [Encore Application Model](/docs/go/concepts/application-model) to automatically generate a Service Catalog along with complete documentation for all APIs. This ensures docs are always up-to-date as your APIs evolve.\n\nThe API docs are available both in your [Local Development Dashboard](/docs/go/observability/dev-dash) and for your whole team in the [Encore Cloud dashboard](https://app.encore.cloud).\n\n\n"
},
{
"path": "docs/go/develop/auth.md",
"content": "---\nseotitle: Adding authentication to APIs to auth users\nseodesc: Learn how to add authentication to your APIs and make sure you know who's calling your backend APIs.\ntitle: Authenticating users\nsubtitle: Knowing what's what and who's who\ninfobox: {\n title: \"Authentication\",\n import: \"encore.dev/beta/auth\",\n}\nlang: go\n---\nAlmost every application needs to know who's calling it, whether the user\nrepresents a person in a consumer-facing app or an organization in a B2B app.\nEncore supports both use cases in a simple yet powerful way.\n\nAs described in the docs for [defining APIs](/docs/go/primitives/defining-apis), Encore offers three access levels\nfor APIs:\n\n* `//encore:api public` – defines a public API that anybody on the internet can call.\n* `//encore:api private` – defines a private API that is never accessible to the outside world. It can only be called from other services in your app and via cron jobs.\n* `//encore:api auth` – defines a public API that anybody can call, but that requires valid authentication.\n\nWhen an API is defined with access level `auth`, outside calls to that API must specify\nan authorization header, in the form `Authorization: Bearer ![](\"/assets/docs/test_trace.png\" "\\"Test")
\n\n\n## Integration testing\n\nSince Encore removes almost all boilerplate, most of the code you write\nis business logic that involves databases and calling APIs between services.\nSuch behavior is most easily tested with integration tests.\n\nWhen running tests, Encore automatically sets up the databases you need\nin a separate database cluster. They are additionally configured to skip `fsync`\nand to use an in-memory filesystem since durability is not a concern for automated tests.\n\nThis drastically reduces the speed overhead of writing integration tests.\n\nIn general, Encore applications tend to focus more on integration tests\ncompared to traditional applications that are heavier on unit tests.\nThis is nothing to worry about and is the recommended best practice.\n\n### Temporary databases\n\nWhen Encore runs tests, by default it reuses the same database for all tests,\nto improve performance. However, this means that you need to take care when writing tests\nto ensure tests don't interfere with each other.\n\nIf you instead want to have a separate database for a given test, you can use\n[`et.NewTestDatabase`](https://pkg.go.dev/encore.dev/et#NewTestDatabase) to create a temporary database\nthat only exists for the duration of the test.\n\nThe temporary test database is a fully-migrated database. It does not include any data written by other tests.\n\n![](\"/assets/docs/auth0-create-app.png\" "\\"Create")
\n\nNext, go to the *Application Settings* section. There you will find the `Domain`, `Client ID`, and `Client Secret` that you need to communicate with Auth0. \nCopy these values, we will need them shortly.\n\n![](\"/assets/docs/auth0-basic-info.png\" "\\"Auth0")
\n\nA callback URL is where Auth0 redirects the user after they have been authenticated. \nAdd `http://localhost:3000/callback` to the *Allowed Callback URLs*. \nYou will need to add more URLs to this list when you have a production or staging environments. \n\nThe same goes for the logout URL (were the user will get redirected after logout). Add `http://localhost:3000/` to the *Allowed Logout URLs*. \n\n![](\"/assets/docs/auth0-app-uris.png\" "\\"Auth0")
\n\n\n## Config and secrets\n\nCreate a [configuration file](/docs/go/develop/config) in the `auth` service and name it `auth-config.cue`. Add the following:\n\n```cue\nClientID: \"![](\"/assets/docs/microservices-service-catalog.png\" "\\"Service")
\n\nAs well as the [Flow architecture diagram](/docs/go/observability/encore-flow).\n\n![](\"/assets/docs/microservices-flow.png\" "\\"Encore")
\n\n## Sharing databases between services (or not)\n\nDeciding whether to share a database between multiple services depends on your specific situation. Encore supports both options. Learn more in the [database documentation](/docs/go/primitives/share-db-between-services).\n\n"
},
{
"path": "docs/go/how-to/cgo.md",
"content": "---\nseotitle: Build Go applications with cgo using Encore\nseodesc: Learn how to build Go applications with cgo using Encore\ntitle: Build with cgo\nlang: go\n---\n\nCgo is a feature of the Go compiler that enables Go programs to interface\nwith libraries written in other languages using C bindings.\n\nBy default, for improved portability Encore builds applications with cgo support disabled.\n\nTo enable cgo for your application, add `\"build\": {\"cgo_enabled\": true}` to your `encore.app` file.\n\nFor example:\n\n```json\n-- encore.app --\n{\n \"id\": \"my-app-id\",\n \"build\": {\n \"cgo_enabled\": true\n }\n}\n```\n\nWith this setting Encore's build system will compile the application using an Ubuntu builder image\nwith gcc pre-installed.\n\n## Static linking\n\nTo keep the resulting Docker images as minimal as possible, Encore compiles applications with static linking.\nThis happens even with cgo enabled. As a result the cgo libraries you use must support static linking.\n\nIn some cases, you may need to add additional linker flags to properly work with static linking of cgo libraries.\nSee the [official cgo docs](https://pkg.go.dev/cmd/cgo) for more information on how to do this.\n"
},
{
"path": "docs/go/how-to/clerk-auth.md",
"content": "---\nseotitle: How to use Clerk to authenticate users in your backend application\nseodesc: Learn how to use Clerk for user authentication in your backend application. In this guide we show you how to integrate your Go backend with Clerk.\ntitle: Use Clerk with your app\nlang: go\n---\n\nIn this guide you will learn how to set up an Encore [auth handler](/docs/go/develop/auth#the-auth-handler) that makes use of\n[Clerk](https://clerk.com/) in order to add an integrated signup and login experience to your web app.\n\nFor all the code and instructions of how to clone and run this example locally, see the [Clerk Example](https://github.com/encoredev/examples/tree/main/clerk) in our examples repo.\n\n## Set up the auth handler\n\nIn your Encore app, install the following module:\n\n```shell\n$ go get github.com/clerkinc/clerk-sdk-go/clerk\n```\n\nCreate a folder and naming it `auth`, this is where our authentication related backend code will live.\n\nIt's time to define your [auth handler](/docs/go/develop/auth). Create `auth/auth.go` and paste the following:\n\n```go\npackage auth\n\nimport (\n\t\"context\"\n\t\"encore.dev/beta/auth\"\n\t\"encore.dev/beta/errs\"\n\t\"github.com/clerkinc/clerk-sdk-go/clerk\"\n)\n\nvar secrets struct {\n\tClientSecretKey string\n}\n\n// Service struct definition.\n// Learn more: encore.dev/docs/primitives/services-and-apis/service-structs\n//\n//encore:service\ntype Service struct {\n\tclient clerk.Client\n}\n\n// initService is automatically called by Encore when the service starts up.\nfunc initService() (*Service, error) {\n\tclient, err := clerk.NewClient(secrets.ClientSecretKey)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn &Service{client: client}, nil\n}\n\ntype UserData struct {\n\tID string `json:\"id\"`\n\tUsername *string `json:\"username\"`\n\tFirstName *string `json:\"first_name\"`\n\tLastName *string `json:\"last_name\"`\n\tProfileImageURL string `json:\"profile_image_url\"`\n\tPrimaryEmailAddressID *string `json:\"primary_email_address_id\"`\n\tEmailAddresses []clerk.EmailAddress `json:\"email_addresses\"`\n}\n\n// The `encore:authhandler` annotation tells Encore to run this function for all\n// incoming API call that requires authentication.\n// Learn more: encore.dev/docs/develop/auth#the-auth-handler\n//\n//encore:authhandler\nfunc (s *Service) AuthHandler(ctx context.Context, token string) (auth.UID, *UserData, error) {\n\t// verify the session\n\tsessClaims, err := s.client.VerifyToken(token)\n\tif err != nil {\n\t\treturn \"\", nil, &errs.Error{\n\t\t\tCode: errs.Unauthenticated,\n\t\t\tMessage: \"invalid token\",\n\t\t}\n\t}\n\n\tuser, err := s.client.Users().Read(sessClaims.Claims.Subject)\n\tif err != nil {\n\t\treturn \"\", nil, &errs.Error{\n\t\t\tCode: errs.Internal,\n\t\t\tMessage: err.Error(),\n\t\t}\n\t}\n\n\tuserData := &UserData{\n\t\tID: user.ID,\n\t\tUsername: user.Username,\n\t\tFirstName: user.FirstName,\n\t\tLastName: user.LastName,\n\t\tProfileImageURL: user.ProfileImageURL,\n\t\tPrimaryEmailAddressID: user.PrimaryEmailAddressID,\n\t\tEmailAddresses: user.EmailAddresses,\n\t}\n\n\treturn auth.UID(user.ID), userData, nil\n}\n```\n\n## Clerk credentials\n\nCreate a Clerk account if you haven't already. Then, in the Clerk dashboard, create a new applications.\n\nNext, go to the *API Keys* page for your app. Copy one of the \"Secret keys\" (the \"Publishable Key\" will be used by your frontend).\n\nThe `Secret key` is sensitive and should not be hardcoded in your code/config. Instead, you should store that as an [Encore secret](/docs/go/primitives/secrets).\n\nFrom your terminal (inside your Encore app directory), run:\n\n```shell\n$ encore secret set --prod ClientSecretKey\n```\n\nNow you should do the same for the development secret. The most secure way is to create another secret key (Clerk allows you to have multiple).\nOnce you have a client secret for development, set it similarly to before:\n\n```shell\n$ encore secret set --dev ClientSecretKey\n```\n\n## Frontend\n\nClerk offers a [React SDK](https://clerk.com/docs/references/react/overview) for the frontend which makes it really simple to integrate \na login/signup flow inside your web app as well as getting the token required to communicate with your Encore backend. \n\nYou can use the `useAuth` hook from `@clerk/clerk-react` to get the token and send it to your backend.\n\n```tsx\nimport { useAuth } from '@clerk/clerk-react';\n \nexport default function ExternalDataPage() {\n const { getToken, isLoaded, isSignedIn } = useAuth();\n \n if (!isLoaded) {\n // Handle loading state however you like\n return ![](\"/assets/docs/logto-api-resource.png\" "\\"Logto")
\n\n3. Create an application for your frontend application\n - Go to \"Applications\" in Logto Console\n - Create a new application according to your frontend framework (We use React as an example, but you can create any Single-Page Application (SPA) or native app)\n - (Optional, we'll cover this later) Integrate Logto with your frontend application according to the guide in the Logto Console.\n - Note down the application ID and issuer URL on the Application details page as we'll need them later\n\n ![](\"/assets/docs/logto-application-endpoints.png\" "\\"Logto")
\n\n## Setup the auth handler\n\nNow let's implement the authentication in your Encore application. We'll use Encore's built-in [auth handler](/docs/go/develop/auth) to validate Logto's JWT tokens.\n\nAdd these two modules in your Encore application:\n\n```shell\n$ go get github.com/golang-jwt/jwt/v5\n$ go get github.com/MicahParks/keyfunc/v3\n```\n\nCreate `auth/auth.go` and add the following code:\n\n```go\npackage auth\n\nimport (\n\t\"context\"\n\t\"time\"\n\n\t\"encore.dev/beta/auth\"\n\t\"encore.dev/beta/errs\"\n\t\"encore.dev/config\"\n\t\"github.com/MicahParks/keyfunc/v3\"\n\t\"github.com/golang-jwt/jwt/v5\"\n)\n\n// Configuration variables for authentication\ntype LogtoAuthConfig struct {\n\t// The issuer URL\n\tIssuer config.String\n\t// URL to fetch JSON Web Key Set (JWKS)\n\tJwksUri config.String\n\t// Expected audience for the JWT\n\tApiResourceIndicator config.String\n\t// Expected client ID in the token claims\n\tClientId config.String\n}\n\nvar authConfig *LogtoAuthConfig = config.Load[*LogtoAuthConfig]()\n\n// RequiredClaims defines the expected structure of JWT claims\n// Extends the standard JWT claims with a custom ClientID field\ntype RequiredClaims struct {\n\tClientID string `json:\"client_id\"`\n\tjwt.RegisteredClaims\n}\n\n// AuthHandler validates JWT tokens and extracts the user ID\n// Implements Encore's authentication handler interface\n//\n//encore:authhandler\nfunc AuthHandler(ctx context.Context, token string) (auth.UID, error) {\n\t// Fetch and parse the JWKS (JSON Web Key Set) from the identity provider\n\tjwks, err := keyfunc.NewDefaultCtx(ctx, []string{authConfig.JwksUri()})\n\tif err != nil {\n\t\treturn \"\", &errs.Error{\n\t\t\tCode: errs.Internal,\n\t\t\tMessage: \"failed to fetch JWKS\",\n\t\t}\n\t}\n\n\t// Parse and validate the JWT token with required claims and validation options\n\tparsedToken, err := jwt.ParseWithClaims(\n\t\ttoken,\n\t\t&RequiredClaims{},\n\t\tjwks.Keyfunc,\n\t\t// Expect the token to be intended for this API resource\n\t\tjwt.WithAudience(authConfig.ApiResourceIndicator()),\n\t\t// Expect the token to be issued by this issuer\n\t\tjwt.WithIssuer(authConfig.Issuer()),\n\t\t// Allow some leeway for clock skew\n\t\tjwt.WithLeeway(time.Minute*10),\n\t)\n\n\t// Check if there were any errors during token parsing\n\tif err != nil {\n\t\treturn \"\", &errs.Error{\n\t\t\tCode: errs.Unauthenticated,\n\t\t\tMessage: \"invalid token\",\n\t\t}\n\t}\n\n\t// Verify that the client ID in the token matches the expected client ID\n\tif parsedToken.Claims.(*RequiredClaims).ClientID != authConfig.ClientId() {\n\t\treturn \"\", &errs.Error{\n\t\t\tCode: errs.Unauthenticated,\n\t\t\tMessage: \"invalid token\",\n\t\t}\n\t}\n\n\t// Extract the user ID (subject) from the token claims\n\tuserId, err := parsedToken.Claims.GetSubject()\n\tif err != nil {\n\t\treturn \"\", &errs.Error{\n\t\t\tCode: errs.Unauthenticated,\n\t\t\tMessage: \"invalid token\",\n\t\t}\n\t}\n\n\t// Return the user ID as an Encore auth.UID\n\treturn auth.UID(userId), nil\n}\n```\n\nCreate a [configuration file](https://encore.dev/docs/go/develop/config) in the auth service and name it `auth-config.cue`. Add the following:\n\n```cue\nIssuer: \"![](\"/assets/docs/flow-highlight.png\" "\\"Encore")
\n\n## Real-time updates\n\nFlow is accessible in the [Local Development Dashboard](/docs/go/observability/dev-dash) and, when using Encore Cloud, in the [Encore Cloud dashboard](https://app.encore.cloud) for cloud environments.\n\nWhen developing locally, Flow will auto update in real-time to reflect your architecture as you\nmake code changes. This helps you be mindful of important dependencies and makes it clear if you introduce new ones.\n\nFor cloud environments, Flow auto-updates with each deploy.\n\nIn the example below a new subscription on the topic `payment-made` is introduced and then removed in `user` service:\n\n\n"
},
{
"path": "docs/go/observability/logging.md",
"content": "---\nseotitle: Use structured logging to understand your application\nseodesc: Learn how to use structured logging, a combination of free-form log messages and type-safe key-value pairs, to understand your backend application's behavior.\ntitle: Logging\nsubtitle: Structured logging helps you understand your application\nlang: go\ninfobox: {\n title: \"Structured Logging\",\n import: \"encore.dev/rlog\",\n}\n---\n\nEncore offers built-in support for Structured Logging, which combines a free-form log message with structured and type-safe key-value pairs. This enables straightforward analysis of what your application is doing, in a way that is easy for a computer to parse, analyze, and index. This makes it simple to quickly filter and search through logs.\n\nEncore’s logging is integrated with the built-in [Distributed Tracing](/docs/go/observability/tracing) functionality, and all logs are automatically included in the active trace. This dramatically simplifies debugging of your application.\n\n## Usage\nFirst, import `encore.dev/rlog` in your package. Then simply call one of the package methods `Info`, `Error`, or `Debug`. For example:\n\n```go\nrlog.Info(\"log message\",\n\t\"user_id\", 12345,\n\t\"is_subscriber\", true)\nrlog.Error(\"something went terribly wrong!\",\n\t\"err\", err)\n```\n\nThe first parameter is the log message. After that follows zero or more key-value pairs for structured logging for context.\n\nIf you’re logging many log messages with the same key-value pairs each time it can be a bit cumbersome. To help with that, use `rlog.With()` to group them into a context object, which then copies the key-value pairs into each log event:\n\n```go\nctx := rlog.With(\"is_subscriber\", true)\nctx.Info(\"user logged in\", \"login_method\", \"oauth\") // includes is_subscriber=true\n```\n\nFor more information, see the [API Documentation](https://pkg.go.dev/encore.dev/rlog).\n\n## Live-streaming logs\n\nEncore also makes it simple to live-stream logs directly to your terminal, from any environment, by running:\n\n```\n$ encore logs --env=prod\n```"
},
{
"path": "docs/go/observability/metrics.md",
"content": "---\nseotitle: Custom metrics in Go\nseodesc: Learn how to define and use custom metrics in your Go backend application with Encore.\ntitle: Metrics\nsubtitle: Track custom metrics in your Go application\ninfobox: {\n title: \"Metrics\",\n import: \"encore.dev/metrics\",\n}\nlang: go\n---\n\nEncore provides built-in support for defining custom metrics in your Go applications. Once defined, metrics are automatically collected and displayed in the Encore Cloud Dashboard, and can be exported to third-party observability services.\n\nSee the [Platform metrics documentation](/docs/platform/observability/metrics) for information about integrations with third-party services like Grafana Cloud and Datadog.\n\n## Defining custom metrics\n\nDefine custom metrics by importing the [`encore.dev/metrics`](https://pkg.go.dev/encore.dev/metrics) package and\ncreating a new metric using one of the `metrics.NewCounter` or `metrics.NewGauge` functions.\n\nFor example, to count the number of orders processed:\n\n```go\nimport \"encore.dev/metrics\"\n\nvar OrdersProcessed = metrics.NewCounter[uint64](\"orders_processed\", metrics.CounterConfig{})\n\nfunc process(order *Order) {\n // ...\n OrdersProcessed.Increment()\n}\n```\n\n## Metric types\n\nEncore currently supports two metric types: counters and gauges.\n\n**Counters** measure the count of something. A counter's value must always increase, never decrease. (Note that the value gets reset to 0 when the application restarts.) Typical use cases include counting the number of requests, the amount of data processed, and so on.\n\n**Gauges** measure the current value of something. Unlike counters, a gauge's value can fluctuate up and down. Typical use cases include measuring CPU usage, the number of active instances running of a process, and so on.\n\nFor information about their respective APIs, see the API documentation for [Counter](https://pkg.go.dev/encore.dev/metrics#Counter) and [Gauge](https://pkg.go.dev/encore.dev/metrics#Gauge).\n\n### Counter example\n\n```go\nimport \"encore.dev/metrics\"\n\nvar RequestsReceived = metrics.NewCounter[uint64](\"requests_received\", metrics.CounterConfig{})\n\nfunc handleRequest() {\n RequestsReceived.Increment()\n // ... handle request\n}\n```\n\n### Gauge example\n\n```go\nimport \"encore.dev/metrics\"\n\nvar ActiveConnections = metrics.NewGauge[int64](\"active_connections\", metrics.GaugeConfig{})\n\nfunc onConnect() {\n ActiveConnections.Add(1)\n}\n\nfunc onDisconnect() {\n ActiveConnections.Add(-1)\n}\n```\n\n## Defining labels\n\nEncore's metrics package provides a type-safe way of attaching labels to metrics. To define labels, create a struct type representing the labels and then use `metrics.NewCounterGroup` or `metrics.NewGaugeGroup`.\n\nThe Labels type must be a named struct, where each field corresponds to a single label. Each field must be of type `string`, `int`, or `bool`.\n\n### Counter with labels\n\n```go\nimport \"encore.dev/metrics\"\n\ntype Labels struct {\n Success bool\n}\n\nvar OrdersProcessed = metrics.NewCounterGroup[Labels, uint64](\"orders_processed\", metrics.CounterConfig{})\n\nfunc process(order *Order) {\n var success bool\n // ... populate success with true/false ...\n OrdersProcessed.With(Labels{Success: success}).Increment()\n}\n```\n\n### Gauge with labels\n\n```go\nimport \"encore.dev/metrics\"\n\ntype ConnectionLabels struct {\n Region string\n}\n\nvar ActiveConnections = metrics.NewGaugeGroup[ConnectionLabels, int64](\"active_connections\", metrics.GaugeConfig{})\n\nfunc onConnect(region string) {\n ActiveConnections.With(ConnectionLabels{Region: region}).Add(1)\n}\n```\n\n![](\"/assets/img/dithered-clouds.png\")
\n ![](\"/assets/icons/features/preview-envs.png\"){kind=icon}
\n ![](\"/assets/icons/features/flow.png\"){kind=icon}
\n ![](\"/assets/docs/pubsub-rpc-example.png\")
\n\n![](\"/assets/docs/pubsub-topic-example.png\")
\n\n![](\"/assets/docs/secrets.png\" "\\"Encore's")
\n\n### Using the CLI\n\nIf you prefer, you can also set up secrets from the CLI using:![](\"/assets/docs/secretoverride.png\" "\\"Overriding")
\n\n## How it works: Where secrets are stored\n\nWhen you store a secret Encore stores it encrypted using Google Cloud Platform's [Key Management Service](https://cloud.google.com/security-key-management) (KMS).\n\n- **Production / Your own cloud:** When you deploy to production using your own cloud account on GCP or AWS, Encore provisions a secrets manager in your account (using either KMS or AWS Secrets Manager) and replicates your secrets to it. The secrets are then injected into the container using secret environment variables.\n- **Local:** For local secrets Encore automatically replicates them to developers' machines when running `encore run`.\n- **Development / Encore Cloud:** Environments on Encore's development cloud (running on GCP under the hood) work the same as self-hosted GCP environments, using GCP Secrets Manager.\n\n### Overriding local secrets\n\nWhen setting secrets via the `encore secret set` command, they are automatically synced to all developers\nworking on the same application, courtesy of Encore Cloud.\n\nIn some cases, however, you want to override a secret only for your local machine.\nThis can be done by creating a file named `.secrets.local.cue` in the root of your Encore application,\nnext to the `encore.app` file.\n\nThe file contains key-value pairs of secret names to secret values. For example:\n\n```cue\nGitHubAPIToken: \"my-local-override-token\"\nSSHPrivateKey: \"custom-ssh-private-key\"\n```\n"
},
{
"path": "docs/go/primitives/service-structs.md",
"content": "---\nseotitle: Service Structs\nseodesc: Learn how to use service structs to define APIs as methods.\ntitle: Service structs\nlang: go\n---\n\nEncore lets you define a type, called a service struct, to represent your running service. This lets you define an initialization function (similar to the `main` function in regular Go programs).\n\nYou can also define API endpoints as methods on the service struct type, enabling you to use [dependency injection](/docs/go/how-to/dependency-injection) for testing purposes.\n\nIt works by defining a struct type of your choice (typically called `Service`)\nand declaring it with `//encore:service`.\nThen, you can define a special function named `initService`\n(or `initWhatever` if you named the type `Whatever`)\nthat gets called by Encore to initialize your service when it starts up.\n\nIt looks like this:\n```go\n//encore:service\ntype Service struct {\n\t// Add your dependencies here\n}\n\nfunc initService() (*Service, error) {\n\t// Write your service initialization code here.\n}\n\n//encore:api public\nfunc (s *Service) MyAPI(ctx context.Context) error {\n\t// ...\n}\n```\n\n![](\"/assets/tutorials/booking-system/user-calendar.png\" "\\"User")
\n\n![](\"/assets/tutorials/booking-system/admin-dashboard.png\" "\\"Admin")
\n\nIf you want to skip ahead you can view the final project here: [https://github.com/encoredev/examples/tree/main/booking-system](https://github.com/encoredev/examples/tree/main/booking-system)\n\n## 1. Create your Encore application\n\n![](\"/assets/tutorials/booking-system/booking-system-flow.png\" "\\"Encore")
\n\n## 2. Create booking service\n\nLet's start by creating the functionality to view bookable slots.\n\nWith Encore you define a service by [defining one or more APIs](/docs/go/primitives/defining-apis) within a regular Go package. Encore recognizes this as a service, and uses the package name as the service name. When deploying, Encore will automatically [provision the required infrastructure](/docs/platform/infrastructure/infra) for each service.\n\nWe already have a Go package named `booking`, let's turn that into an Encore service.\n\n🥐 Inside the `booking` folder, create a file named `slots.go`.\n\n```shell\n$ touch booking/slots.go\n```\n\n🥐 Add an Encore API endpoint named `GetBookableSlots` that takes a date as input. The endpoint will return a list of bookable slots from the supplied date and six days forward (so that we can show a week view calendar in the UI).\n\n```go\n-- booking/slots.go --\n// Service booking keeps track of bookable slots in the calendar.\npackage booking\n\nimport (\n\t\"context\"\n\t\"github.com/jackc/pgx/v5/pgtype\"\n\t\"time\"\n)\n\nconst DefaultBookingDuration = 1 * time.Hour\n\ntype BookableSlot struct {\n\tStart time.Time `json:\"start\"`\n\tEnd time.Time `json:\"end\"`\n}\n\ntype SlotsParams struct{}\n\ntype SlotsResponse struct{ Slots []BookableSlot }\n\n//encore:api public method=GET path=/slots/:from\nfunc GetBookableSlots(ctx context.Context, from string) (*SlotsResponse, error) {\n\tfromDate, err := time.Parse(\"2006-01-02\", from)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tconst numDays = 7\n\n\tvar slots []BookableSlot\n\tfor i := 0; i < numDays; i++ {\n\t\tdate := fromDate.AddDate(0, 0, i)\n\t\tdaySlots, err := bookableSlotsForDay(date)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tslots = append(slots, daySlots...)\n\t}\n\n\treturn &SlotsResponse{Slots: slots}, nil\n}\n\nfunc bookableSlotsForDay(date time.Time) ([]BookableSlot, error) {\n\t// 09:00\n\tavailStartTime := pgtype.Time{\n\t\tValid: true,\n\t\tMicroseconds: int64(9*3600) * 1e6,\n\t}\n\t// 17:00\n\tavailEndTime := pgtype.Time{\n\t\tValid: true,\n\t\tMicroseconds: int64(17*3600) * 1e6,\n\t}\n\n\tavailStart := date.Add(time.Duration(availStartTime.Microseconds) * time.Microsecond)\n\tavailEnd := date.Add(time.Duration(availEndTime.Microseconds) * time.Microsecond)\n\n\t// Compute the bookable slots in this day, based on availability.\n\tvar slots []BookableSlot\n\tstart := availStart\n\tfor {\n\t\tend := start.Add(DefaultBookingDuration)\n\t\tif end.After(availEnd) {\n\t\t\tbreak\n\t\t}\n\t\tslots = append(slots, BookableSlot{\n\t\t\tStart: start,\n\t\t\tEnd: end,\n\t\t})\n\t\tstart = end\n\t}\n\n\treturn slots, nil\n}\n```\n\nThe availability is currently hardcoded to be 09:00 - 17:00 for each day. Later we'll add the functionality to set it for each day of the week.\nWe are also returning time slots that have already passed. Don't worry, we'll come back and fix it later on.\n\n🥐 Let's try it! Open up the Local Development Dashboard running at [http://localhost:9400](http://localhost:9400) and try calling\nthe `booking.GetBookableSlots` endpoint, passing in `2024-12-01`.\n\nIf you prefer to use the terminal instead run `curl http://localhost:4000/slots/2024-12-01` in\na new terminal instead. Either way you should see the response:\n\n```json\n{\n \"Slots\": [\n {\n \"start\": \"2024-12-01T09:00:00Z\",\n \"end\": \"2024-12-01T10:00:00Z\"\n },\n {\n \"start\": \"2024-12-01T10:00:00Z\",\n \"end\": \"2024-12-01T11:00:00Z\"\n },\n {\n \"start\": \"2024-12-01T11:00:00Z\",\n \"end\": \"2024-12-01T12:00:00Z\"\n },\n ...\n ]\n}\n```\n\n## 3. Book an appointment\n\nNext, we want to make it possible to book an appointment. We'll need a database to store the bookings in. Encore makes it really simple to [create and use databases](/docs/go/primitives/databases) (both for local and cloud environments), but for this example we will also make use of [sqlc](https://sqlc.dev/) that will compile our SQL queries into type-safe Go code that we can use in our application.\n\n🥐 Let's create a SQL database for our booking service and the required sqlc scaffolding. Create the following file structure:\n\n```\n/my-app\n└── booking // booking service (a Go package)\n ├── db // (New) db related files (directory)\n │ ├── migrations // (New) db migrations (directory)\n │ │ └── 1_create_tables.up.sql // (New) db migration schema\n │ └── query.sql // (New) SQL queries\n ├── sqlc.yaml // (New) sqlc config file\n ├── slots.go // booking service code\n └── helpers.go // booking service code\n```\n\n🥐 Naming of the database migration file is important, it must look something like: `1_![\"Creating](\"/assets/docs/incident-slack-app-creation.png\")
\n\n🥐 Once you have your Webhook URL which starts with `https://hooks.slack.com/services/...` then copy and paste that and run the following commands to save these as secrets. We recommend having a different webhook/channel for development and production.\n\n```shell\n$ encore secret set --type dev,local,pr SlackWebhookURL\n$ encore secret set --type prod SlackWebhookURL\n```\n\n🥐 Next, let's create our `slack` service that contains the logic for calling the Webhook URL in order to post notifications to our Slack. To do this we need to implement our code in `slack/slack.go`:\n\n```go\n// Service slack calls a webhook to post notifications to Slack.\npackage slack\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"encoding/json\"\n\t\"encore.dev/beta/errs\"\n\t\"io\"\n\t\"net/http\"\n)\n\ntype NotifyParams struct {\n\tText string `json:\"text\"`\n}\n\n//encore:api private\nfunc Notify(ctx context.Context, p *NotifyParams) error {\n\teb := errs.B()\n\treqBody, err := json.Marshal(p)\n\tif err != nil {\n\t\treturn err\n\t}\n\treq, err := http.NewRequestWithContext(ctx, \"POST\", secrets.SlackWebhookURL, bytes.NewReader(reqBody))\n\tif err != nil {\n\t\treturn err\n\t}\n\tresp, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tdefer resp.Body.Close()\n\n\tif resp.StatusCode >= 400 {\n\t\tbody, _ := io.ReadAll(resp.Body)\n\t\treturn eb.Code(errs.Unavailable).Msgf(\"notify slack: %s: %s\", resp.Status, body).Err()\n\t}\n\treturn nil\n}\n\nvar secrets struct {\n\tSlackWebhookURL string\n}\n```\n\n![\"Deploy](\"https://encore.cloud/assets/img/deploy.svg\")
![\"Infra](\"/assets/docs/infra_tab.png\")
\n\n🥐 Now let's call the API again from the local development dashboard, or from the terminal:\n\n```shell\n$ curl http://localhost:4000/url -d '{\"URL\": \"https://encore.dev\"}'\n```\n\n🥐 Finally, let's verify that it was saved in the database. You can do this by checking the trace in the local development dashboard, or you can run `encore db shell url` from the app root directory and inputting `select * from url;`:\n\n```shell\n$ encore db shell url\npsql (13.1, server 11.12)\nType \"help\" for help.\n\nurl=# select * from url;\n id | original_url\n----------+--------------------\n zr6RmZc4 | https://encore.dev\n(1 row)\n```\n\nThat was easy!\n\n## 3. Add endpoint to retrieve URLs\nTo complete our URL shortener API, let’s add the endpoint to retrieve a URL given its short id.\n\n🥐 Add this endpoint to `url/url.go`:\n\n```go\n-- url/url.go --\n// Get retrieves the original URL for the id.\n//encore:api public method=GET path=/url/:id\nfunc Get(ctx context.Context, id string) (*URL, error) {\n\tu := &URL{ID: id}\n\terr := db.QueryRow(ctx, `\n SELECT original_url FROM url\n WHERE id = $1\n `, id).Scan(&u.URL)\n\treturn u, err\n}\n```\n\nEncore uses the `path=/url/:id` syntax to represent a path with a parameter. The `id` name corresponds to the parameter name in the function signature. In this case it is of type `string`, but you can also use other built-in types like `int` or `bool` if you want to restrict the values.\n\n🥐 We can make sure it works by reviewing the endpoint in the Service Catalog in the local development dashboard, where we can call it using the `id` you got in the previous step:\n\n\n\nYou can also call it directly from the terminal:\n\n```shell\n$ curl http://localhost:4000/url/zr6RmZc4\n```\n\nYou should now see this:\n\n```json\n{\n \"ID\": \"zr6RmZc4\",\n \"URL\": \"https://encore.dev\"\n}\n```\n\nIt works! That's how you build REST APIs and use PostgreSQL databases in Encore.\n\n## 4. Add a test\n\nBefore deployment, it is good practice to have tests to assure that\nthe service works properly. Such tests including database access\nare easy to write.\n\nWe've prepared a test to check that the whole cycle of shortening\nthe URL, storing and then retrieving the original URL works.\n\n🥐 Save this in a separate file `url/url_test.go`.\n\n```go\n-- url/url_test.go --\npackage url\n\nimport (\n\t\"context\"\n\t\"testing\"\n)\n\n// TestShortenAndRetrieve - test that the shortened URL is stored and retrieved from database.\nfunc TestShortenAndRetrieve(t *testing.T) {\n\ttestURL := \"https://github.com/encoredev/encore\"\n\tsp := ShortenParams{URL: testURL}\n\tresp, err := Shorten(context.Background(), &sp)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\twantURL := testURL\n\tif resp.URL != wantURL {\n\t\tt.Errorf(\"got %q, want %q\", resp.URL, wantURL)\n\t}\n\n\tfirstURL := resp\n\tgotURL, err := Get(context.Background(), firstURL.ID)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\tif *gotURL != *firstURL {\n\t\tt.Errorf(\"got %v, want %v\", *gotURL, *firstURL)\n\t}\n}\n```\n\n🥐 Now run `encore test ./...` to verify that it's working.\n\nIf you use the local development dashboard ([localhost:9400](http://localhost:9400)), you can even see traces for tests.\n\n## 5. Deploy\n\n![](\"/assets/tutorials/uptime/frontend.png\" "\\"Frontend\\"")
\n\n![](\"/assets/tutorials/uptime/encore-flow.png\" "\\"Encore")
\n\n## 2. Create monitor service\n\nLet's start by creating the functionality to check if a website is currently up or down.\nLater we'll store this result in a database so we can detect when the status changes and\nsend alerts.\n\n🥐 Create an Encore service named `monitor` containing a file named `ping.go`.\n\n```shell\n$ mkdir monitor\n$ touch monitor/ping.go\n```\n\n🥐 Add an Encore API endpoint named `Ping` that takes a URL as input and returns a response\nindicating whether the site is up or down.\n\n```go\n-- monitor/ping.go --\n// Service monitor checks if a website is up or down.\npackage monitor\n\nimport (\n\t\"context\"\n\t\"net/http\"\n\t\"strings\"\n)\n\n// PingResponse is the response from the Ping endpoint.\ntype PingResponse struct {\n\tUp bool `json:\"up\"`\n}\n\n// Ping pings a specific site and determines whether it's up or down right now.\n//\n//encore:api public path=/ping/*url\nfunc Ping(ctx context.Context, url string) (*PingResponse, error) {\n // If the url does not start with \"http:\" or \"https:\", default to \"https:\".\n\tif !strings.HasPrefix(url, \"http:\") && !strings.HasPrefix(url, \"https:\") {\n\t\turl = \"https://\" + url\n\t}\n\n // Make an HTTP request to check if it's up.\n\treq, err := http.NewRequestWithContext(ctx, \"GET\", url, nil)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tresp, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\treturn &PingResponse{Up: false}, nil\n\t}\n\tresp.Body.Close()\n\n // 2xx and 3xx status codes are considered up\n up := resp.StatusCode < 400\n return &PingResponse{Up: up}, nil\n}\n```\n\n🥐 Let's try it! Run `encore run` in your terminal and you should see the service start up.\n\nThen open up the Local Development Dashboard at [http://localhost:9400](http://localhost:9400) and try calling the `monitor.ping` endpoint from the API Explorer, passing in `google.com` as the URL.\n\nYou can then see the response, logs, and view a trace of the request. It will look something like this:\n\n\n\nIf you prefer to use the terminal instead run `curl http://localhost:4000/ping/google.com` in\na new terminal instead. Either way you should see the response:\n\n```json\n{\"up\": true}\n```\n\nYou can also try with `httpstat.us/400` and `some-non-existing-url.com` and it should respond with `{\"up\": false}`.\n(It's always a good idea to test the negative case as well.)\n\n### Add a test\n\n🥐 Let's write an automated test so we don't break this endpoint over time. Create the file `monitor/ping_test.go`\nwith the content:\n\n```go\n-- monitor/ping_test.go --\npackage monitor\n\nimport (\n\t\"context\"\n\t\"testing\"\n)\n\nfunc TestPing(t *testing.T) {\n\tctx := context.Background()\n\ttests := []struct {\n\t\tURL string\n\t\tUp bool\n\t}{\n\t\t{\"encore.dev\", true},\n\t\t{\"google.com\", true},\n // Test both with and without \"https://\"\n\t\t{\"httpbin.org/status/200\", true},\n\t\t{\"https://httpbin.org/status/200\", true},\n\n // 4xx and 5xx should considered down.\n\t\t{\"httpbin.org/status/400\", false},\n\t\t{\"https://httpbin.org/status/500\", false},\n // Invalid URLs should be considered down.\n\t\t{\"invalid://scheme\", false},\n\t}\n\n\tfor _, test := range tests {\n\t\tresp, err := Ping(ctx, test.URL)\n\t\tif err != nil {\n\t\t\tt.Errorf(\"url %s: unexpected error: %v\", test.URL, err)\n\t\t} else if resp.Up != test.Up {\n\t\t\tt.Errorf(\"url %s: got up=%v, want %v\", test.URL, resp.Up, test.Up)\n\t\t}\n\t}\n}\n```\n\n🥐 Run `encore test ./...` to check that it all works as expected. You should see something like:\n\n```shell\n$ encore test ./...\n9:38AM INF starting request endpoint=Ping service=monitor test=TestPing\n9:38AM INF request completed code=ok duration=71.861792 endpoint=Ping http_code=200 service=monitor test=TestPing\n[... lots more lines ...]\nPASS\nok encore.app/monitor 1.660\n```\n\nAnd if you open the local development dashboard at [localhost:9400](http://localhost:9400), you can also see traces for the tests.\n\n## 3. Create site service\n\nNext, we want to keep track of a list of websites to monitor.\n\nSince most of these APIs will be simple \"CRUD\" (Create/Read/Update/Delete) endpoints, let's build this service using [GORM](https://gorm.io/), an ORM\nlibrary that makes building CRUD endpoints really simple.\n\n🥐 Let's create a new service named `site` with a SQL database. To do so, create a new directory `site` in the application root with `migrations` folder inside that folder:\n\n```shell\n$ mkdir site\n$ mkdir site/migrations\n```\n\n🥐 Add a database migration file inside that folder, named `1_create_tables.up.sql`.\nThe file name is important (it must look something like `1_![](\"/assets/docs/microservices-process-allocation.png\" "\\"Microservices")
\n\n## Setting a Primary environment\n\nEvery Encore app has a configurable Primary environment that serves as the default for:\n- App insights in the Encore Cloud dashboard\n- API documentation\n- CLI functionality (like API client generation)\n\n**Configuring your Primary environment:**\n1. Open your app in the [Encore Cloud dashboard](https://app.encore.cloud)\n2. Navigate to **Settings** > **General** > **Primary Environment**\n3. Select your desired environment from the dropdown\n4. Click **Update**\n"
},
{
"path": "docs/platform/deploy/own-cloud.md",
"content": "---\nseotitle: Connect your cloud account to deploy to any cloud\nseodesc: Learn how to deploy your backend application to all the major cloud providers (AWS or GCP) using Encore.\ntitle: Connect your cloud account\nsubtitle: Whatever cloud you prefer is fine by us\nlang: platform\n---\n\nEncore Cloud lets you deploy your application to any of the major cloud providers, using your own cloud account.\nThis lets you use Encore to improve your experience and productivity, while keeping the reliability of a major cloud provider.\n\nEach [environment](/docs/platform/deploy/environments) can be configured to use a different cloud provider, and you can have as many environments as you wish.\nThis also lets you easily deploy a hybrid or multi-cloud application, as you see fit.\n\n![](\"/assets/docs/pr-neon.png\" "\\"Use")
\n\n## Frontend Collaboration\n\nPreview Environments make it really easy to collaborate and test changes with your frontend. Just update your frontend API client to point to the `pr:#` environment.\nThis is a one-line change since your API client always specifies the environment name, e.g. `https://![](\"/assets/docs/infra_config.png\" "\\"Infra")
\n\n#### Process allocation configuration\n\nEncore provides a powerful configuration option called process allocation. This enables you to configure how microservices should be deployed on the compute hardware; either deploying all services in one process or one process per service. All without any code changes.\n\nIt's often recommended to deploy all services in one process in order to reduce costs and minimize response times between services. (But it depends on your use case.)\nDeploying each service as its own process will improve scalability and decrease blast radius if things go wrong. This is only recommended for production environments.\n\n![](\"/assets/docs/gcp-diagram.png\" "\\"Migration")
\n\n## Core Infrastructure Components\n\n### Networking Architecture\n\nTo ensure maximum security and isolation, Encore Cloud provisions a dedicated GCP Project for each environment. This project isolation prevents any potential cross-environment access and enables granular control over resources and permissions. Within each project, all resources are deployed into a private network configuration, where they can only communicate with other resources inside the VPC. This private networking approach significantly reduces the attack surface by preventing direct access from the public internet, with traffic only flowing through designated ingress points.\n\n### Container Management\n\nEncore Cloud provisions a [Google Container Registry (GCR)][gcp-gcr] to store your application's Docker images.\n\nThe registry implements comprehensive access controls to ensure only authorized users and services can access and manage container images. Through integration with GCP's Identity and Access Management (IAM), each service is granted the minimum required permissions needed to pull its container images.\n\nAdditionally, GCR performs automated vulnerability scanning on all container images. As new images are pushed to the registry, they are automatically analyzed for known security vulnerabilities in the operating system and application dependencies. This proactive scanning helps identify potential security issues early in the deployment pipeline, allowing you to maintain a secure application environment.\n\n### Secrets Management\n\nEncore Cloud's integration with Secret Manager provides comprehensive security and seamless access to sensitive data. All secrets are automatically injected as environment variables into your services, eliminating the need for manual configuration while maintaining security. The secrets are protected using industry-standard encryption both when stored and during transmission between services. To ensure maximum security, Secret Manager implements strict access controls - each service can only access the specific secrets it needs, and all access attempts are logged and audited.\n\n## Compute Options\n\nEncore Cloud provisions one of two compute platforms for running your application containers, based on your choice:\n\n### Google Cloud Run\n\nWhen using Cloud Run, Encore Cloud configures:\n\n**Service Deployments**\nEach service is configured with optimized container settings and health check configurations to ensure reliable operation. Environment variables are automatically injected from Secret Manager to securely provide configuration values. Service discovery integration enables seamless communication between services.\n\n**Cloud Run Services**\nCloud Run services are configured with zero-downtime deployment strategies, ensuring your application remains available during updates. Each service is integrated with a load balancer to distribute traffic efficiently across instances. Health check grace periods are configured to allow containers adequate time to start up before receiving traffic, preventing premature termination of healthy instances.\n\n**IAM Configuration**\nEach deployment receives its own dedicated service account to ensure proper isolation and security. These service accounts are automatically configured with the minimum required permissions needed for operation. This includes access to pull container images from Google Container Registry, write application logs to Cloud Logging, and interact with assigned GCP resources like Cloud Storage buckets and Pub/Sub topics. The service accounts are also granted permission to read secrets from Secret Manager, enabling secure access to sensitive configuration values. This automated permission management ensures your services have exactly the access they need while following security best practices.\n\n### Google Kubernetes Engine\n\nWhen using GKE, Encore Cloud configures:\n\n- **Cluster Setup**\n Encore Cloud provisions either GKE Autopilot clusters or standard GKE clusters with managed node pools, both configured to run in private subnets for enhanced security. With Autopilot, GKE automatically manages the underlying infrastructure, while with standard clusters Encore Cloud configures and maintains optimized node pools based on your workload requirements. In both cases, the nodes are placed in private subnets to ensure they're not directly accessible from the internet, with all traffic flowing through the load balancer.\n\n- **Kubernetes Resources**\n Encore Cloud automatically creates and manages all necessary Kubernetes resources for your application. Each Encore service is deployed as a Kubernetes Deployment, ensuring reliable operation and scaling capabilities. These deployments are backed by service accounts configured with appropriate IAM roles to access GCP resources securely. Sensitive configuration data is stored as Kubernetes Secrets and automatically mounted into the appropriate pods. To enable network connectivity, Encore Cloud provisions Kubernetes Service and Ingress resources that integrate with the Google Cloud Load Balancer, providing secure external access to your application endpoints.\n\n- **Load Balancer Integration**\n Encore Cloud integrates with Google Cloud Load Balancer to provide secure and reliable access to your applications. The load balancer is configured to distribute traffic across your services while handling SSL/TLS termination. All traffic is automatically encrypted using managed SSL/TLS certificates that are provisioned and renewed automatically. This ensures your application endpoints remain secure and accessible through HTTPS without requiring manual certificate management.\n\n- **Monitoring Setup**\n Encore Cloud sets up comprehensive monitoring for your GKE clusters by configuring both metrics collection and log management. Container metrics are automatically collected from each pod and exported to your configured monitoring service, providing detailed insights into resource usage, performance, and application behavior. Additionally, all container logs are seamlessly forwarded to Cloud Logging, enabling centralized log aggregation and analysis. This integrated monitoring approach gives you full visibility into your application's health and performance within the Google Cloud ecosystem.\n\n- **Service Accounts**\n Encore Cloud implements a comprehensive service account management system that ensures secure and controlled access to GCP resources. Each service in your application receives its own dedicated service account, providing fine-grained access control and isolation between services.\n\n These service accounts are automatically configured with IAM roles that map precisely to the GCP services your application needs to interact with. The permission configuration is handled dynamically based on your application's declared resource usage. For example, if your service needs to access a GCS bucket, Encore Cloud automatically grants the minimum required permissions for those specific storage operations. Similarly, when your service needs to publish or subscribe to Pub/Sub topics, connect to databases, or retrieve secrets, the appropriate IAM roles are configured automatically.\n\n This automated permission management ensures that each service operates under the principle of least privilege, having access only to the resources it explicitly needs to function. This significantly enhances your application's security posture by minimizing the potential impact of any security breach.\n\nAll of these configurations are automatically maintained and updated by Encore Cloud as you develop your application, ensuring your infrastructure stays aligned with your application's needs.\n\n## Managed Services\n\n### Databases\n\nEncore Cloud provisions [GCP Cloud SQL][gcp-cloudsql] for PostgreSQL databases, providing a robust and scalable database solution:\n\nEncore Cloud provisions Cloud SQL instances running the latest PostgreSQL version, ensuring you have access to the newest features and security updates. Each instance starts with the smallest available configuration to optimize costs, while maintaining the ability to automatically scale up resources as your application's needs grow.\n\nData protection is a key priority, with automated daily backups retained for 7 days and point-in-time recovery capabilities. This allows you to restore your database to any moment within the retention period if needed.\n\nSecurity is enforced through strategic placement of databases in private subnets, isolating them from direct internet access. Strict access controls ensure that only authorized services and users can connect to the database instances.\n\n### Pub/Sub\n\nEncore Cloud implements a robust messaging system using [GCP Pub/Sub][gcp-pubsub]. The system is designed with reliability and security in mind, automatically configuring dead-letter topics to capture and preserve any failed messages for later analysis and debugging. Each service in your application receives precisely scoped IAM permissions for publishing and consuming messages, ensuring secure communication between components while maintaining the principle of least privilege. Encore Cloud fully manages all subscriptions and topics, handling the complex setup and ongoing maintenance of your messaging infrastructure, allowing you to focus on your application logic rather than infrastructure management.\n\n### Object Storage\n\nEncore Cloud leverages [Google Cloud Storage][gcp-gcs] for object storage needs. When you declare storage buckets in your application, Encore Cloud automatically provisions them with unique names in GCP. Each service that interacts with storage is configured with precisely scoped permissions, ensuring secure access to only the buckets and operations it requires. For public buckets, Encore Cloud integrates with Cloud CDN to optimize content delivery, with each bucket accessible through a unique URL. This comprehensive setup provides secure, efficient, and easily manageable object storage capabilities for your application.\n\n### Caching\n\nEncore Cloud uses [GCP Memorystore for Redis][gcp-redis] to provide a high-performance caching solution. Each Redis instance starts with the smallest available configuration to optimize costs while maintaining the ability to automatically scale up resources as your application's caching needs grow. The instances are configured in a high-availability setup to ensure your cache remains available and performant even during infrastructure updates or zone outages. Access to the cache is secured through Redis authentication, with credentials automatically managed and rotated by Encore Cloud to maintain a strong security posture.\n\n### Cron Jobs\n\nEncore Cloud provides a streamlined approach to scheduled task execution that prioritizes both simplicity and security. Each cron job is executed through authenticated API requests that are cryptographically signed, ensuring that only legitimate, verified requests can trigger your scheduled tasks. The system includes robust source verification that validates all requests originate from Encore Cloud's trusted cron infrastructure. This elegant implementation requires no additional infrastructure components, making it both cost-effective and easy to maintain while providing the reliability and security needed for production workloads.\n\n[gcp-vpc]: https://cloud.google.com/vpc\n[gcp-cloudrun]: https://cloud.google.com/run\n[gcp-gke]: https://cloud.google.com/kubernetes-engine\n[gcp-secrets]: https://cloud.google.com/secret-manager\n[gcp-pubsub]: https://cloud.google.com/pubsub\n[gcp-gcs]: https://cloud.google.com/storage\n[gcp-cloudsql]: https://cloud.google.com/sql\n[gcp-redis]: https://cloud.google.com/memorystore\n[gcp-gcr]: https://cloud.google.com/container-registry\n"
},
{
"path": "docs/platform/infrastructure/import-cloud-sql.md",
"content": "---\nseotitle: How to deploy your Encore application with an existing Cloud SQL instance\nseodesc: Learn how to easily import your existing Cloud SQL instance and connect your Encore application to it.\ntitle: Import an existing Cloud SQL instance\nsubtitle: Using your pre-existing database instead of provisioning a new one\nlang: platform\n---\n\n# Overview\n\nWhen deploying applications to your own cloud, Encore Cloud can provision all necessary infrastructure—including database instances. However, if you already have a Cloud SQL instance, you can connect your Encore application directly to this existing database.\n\n## Benefits\n\nUsing an existing Cloud SQL instance allows you to:\n- Maintain data continuity with your existing systems\n- Preserve specific database configurations\n- Utilize familiar database setups without migration\n\n## Importing a Cloud SQL instance\n\nFollow these steps to import your existing Cloud SQL instance:\n\n1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)\n2. Select the GCP cloud provider\n3. Choose **Import Existing Cloud SQL Instance**\n4. Add permissions for the Encore Service Account:\n - Copy the `Encore GCP Service Account` from the cloud dashboard\n - Go to your project's IAM page in the GCP Console\n - Grant the `Owner` role to the `Encore GCP Service Account`\n5. Return to the Encore Cloud dashboard\n6. Specify your database's `GCP Project ID` and `Cloud SQL Instance Name`\n7. Click the `Resolve` button to validate the instance\n\nOnce validated, you can create the environment. When you deploy to this environment, Encore Cloud will automatically connect your application to your imported Cloud SQL instance rather than provisioning a new database.\n\n## Mapping existing databases to your Encore app\nTo access an existing database in your Encore application, you need to specify the name of the existing database when you declare the database in your app. For example, if you have an existing database called `mydb` you can create a reference to it like so:\n\n```typescript\nconst db = new SQLDatabase(\"mydb\");\n```\n\n```go\nsqldb.NewDatabase(\"mydb\", sqldb.DatabaseConfig{\n\tMigrations: \"./migrations\",\n})\n```\n\n## Applying migrations to existing databases\nEncore uses a table called `schema_migrations` in the public namespace to keep track of which migrations have been applied. If you import an existing database without that table, Encore will create it for you and apply your migrations in order. If the table already exists, Encore expects it to contain exactly two columns:\n\n```\nversion bigint\ndirty boolean\n```\n\nIf the table exists but has a different schema, you will not be able to import it with Encore at this time. If the table exists with an existing entry, Encore will apply all higher versions in your `migrations` directory to the database.\n"
},
{
"path": "docs/platform/infrastructure/import-kubernetes-cluster.md",
"content": "---\nseotitle: How to deploy your Encore application to an existing Kubernetes cluster\nseodesc: Learn how to easily import your existing Kubernetes cluster and deploy your Encore application into it.\ntitle: Import an existing Kubernetes cluster\nsubtitle: Deploying to your pre-existing cluster instead of provisioning a new one\nlang: platform\n---\n\nWhen you deploy your application to your own cloud, Encore Cloud can provision infrastructure for it in many different ways – including setting up a Kubernetes cluster.\n\nIf you already have a Kubernetes cluster, Encore Cloud can deploy your Encore application into this pre-existing cluster. This is often useful if you want to integrate your Encore application with other parts of your system that are not built using Encore.\n\nKubernetes imports are supported on GCP, AWS support is coming soon.\n\n## Importing a cluster\n\nTo import your cluster, go to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud), select **Kubernetes: Existing GKE Cluster** as the compute platform, and then specify your cluster's `Project ID`, `Region`, and `Cluster Name`.\n\nWhen you deploy to this environment, Encore Cloud will use your imported cluster as the compute instance.\n\n![](\"/assets/docs/import-k8s.png\" "\\"Import")
\n"
},
{
"path": "docs/platform/infrastructure/import-project.md",
"content": "---\nseotitle: How to deploy your Encore application to an existing GCP project\nseodesc: Learn how to easily import your existing GCP project and connect your Encore application to it.\ntitle: Import an existing GCP project\nsubtitle: Using your pre-existing GCP project instead of provisioning a new one\nlang: platform\n---\n\n# Overview\n\nWhen deploying applications to your own cloud, Encore Cloud can provision all necessary infrastructure—including new GCP projects. However, if you already have a GCP project, you can deploy your Encore application directly to this existing project.\n\n## Benefits\n\nUsing an existing GCP project allows you to:\n- Keep all your infrastructure in a single project\n- Maintain existing IAM policies and permissions\n- Utilize existing billing settings and quotas\n- Consolidate resources for easier management\n\n## Importing a GCP project\n\nFollow these steps to import your existing GCP project:\n\n1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)\n2. Select the GCP cloud provider\n3. Choose **Import Project**\n4. Add permissions for the Encore Service Account:\n - Copy the `Encore GCP Service Account` from the cloud dashboard\n - Go to your project's IAM page in the GCP Console\n - Grant the `Owner` role to the `Encore GCP Service Account`\n5. Return to the Encore Cloud dashboard\n6. Enter your `Project ID` \n7. Click the `Resolve` button to validate the project\n\nOnce validated, you can create the environment. When you deploy to this environment, Encore Cloud will automatically deploy your application to your imported GCP project rather than provisioning a new one. "
},
{
"path": "docs/platform/infrastructure/import-rds.md",
"content": "---\nseotitle: How to deploy your Encore application with an existing AWS RDS instance\nseodesc: Learn how to easily import your existing AWS RDS instance and connect your Encore application to it.\ntitle: Import an existing AWS RDS instance\nsubtitle: Using your pre-existing database instead of provisioning a new one\nlang: platform\n---\n\n# Overview\n\nWhen deploying applications to your own cloud, Encore Cloud can provision all necessary infrastructure—including database instances. However, if you already have an AWS RDS instance, you can connect your Encore application directly to this existing database.\n\n## Benefits\n\nUsing an existing AWS RDS instance allows you to:\n- Maintain data continuity with your existing systems\n- Preserve specific database configurations\n- Utilize familiar database setups without migration\n\n## Importing an AWS RDS instance\n\nFollow these steps to import your existing AWS RDS instance:\n\n1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)\n2. Select the AWS cloud provider\n3. Pick the `AWS Region` your database resides in\n3. Choose **Import Existing RDS Instance**\n4. Specify your database's `RDS Instance Name`\n5. Click the `Resolve` button to validate the instance\n\nOnce validated, you can create the environment. When you deploy to this environment, Encore Cloud will automatically connect your application to your imported AWS RDS instance rather than provisioning a new database.\n\n## Mapping existing databases to your Encore app\nTo access an existing database in your Encore application, you need to specify the name of the existing database when you declare the database in your app. For example, if you have an existing database called `mydb` you can create a reference to it like so:\n\n```typescript\nconst db = new SQLDatabase(\"mydb\");\n```\n\n```go\nsqldb.NewDatabase(\"mydb\", sqldb.DatabaseConfig{\n\tMigrations: \"./migrations\",\n})\n```\n\n## Applying migrations to existing databases\nEncore uses a table called `schema_migrations` in the public namespace to keep track of which migrations have been applied. If you import an existing database without that table, Encore will create it for you and apply your migrations in order. If the table already exists, Encore expects it to contain exactly two columns:\n\n```\nversion bigint\ndirty boolean\n```\n\nIf the table exists but has a different schema, you will not be able to import it with Encore at this time. If the table exists with an existing entry, Encore will apply all higher versions in your `migrations` directory to the database.\n"
},
{
"path": "docs/platform/infrastructure/infra.md",
"content": "---\nseotitle: Cloud Infrastructure Provisioning\nseodesc: Learn how to provision appropriate cloud infrastructure depending on the environment type for AWS and GCP.\ntitle: Infrastructure provisioning & Environments\nsubtitle: How Encore Cloud provisions infrastructure for your application\nlang: platform\n---\n\nEncore Cloud 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](/docs/platform/deploy/own-cloud) and create an environment.\n\n![](\"/assets/docs/encore_overview.png\" "\\"Infrastructure")
\n\n## How it works\n\nThis is powered by Encore's open source [backend framework](/docs/ts), which lets you declare infrastructure resources (databases, caches, queues, scheduled jobs, etc.) as type-safe objects in application code.\n\nAt compile time, Encore parses the application code to generate an [Application Model](/docs/ts/concepts/application-model), and Encore Cloud uses this meta data to create an infrastructure graph with a high-resolution definition of the infrastructure your application requires.\n\nEncore Cloud then uses this graph to provision and manage the necessary infrastructure in your cloud account (using AWS and GCP APIs), and in development and preview environments hosted by Encore Cloud.\n\n![](\"/assets/docs/howitworks.png\" "\\"Infrastructure")
\n\n\nThe approach removes the need for infrastructure configuration files and avoids creating cloud-specific dependencies in your application.\n\nHaving an end-to-end integration between application code and infrastructure also enables Encore Cloud to keep environments in sync and track cloud infrastructure, giving you an up-to-date view of your infrastructure to avoid unnecessary cloud costs.\n\n![](\"/assets/docs/infra_config_new.png\" "\\"Infrastructure")
\n\n## Environment types\n\nBy default, Encore Cloud provisions infrastructure using contextually appropriate objectives for each environment type. You retain control over the infrastructure in your cloud account, and can configure it directly both via the Encore Cloud dashboard and your cloud provider's console. Encore Cloud takes care of syncing your changes.\n\n| | Local | Encore Cloud Hosting | GCP / AWS |\n| ---------------------- | ------------------ | -------------------------- | ---------------------------------- |\n| **Environment types:** | Development | Preview, Development | Development, Production |\n| **Objectives:** | Provisioning speed | Provisioning speed, Cost\\* | Reliability, Security, Scalability |\n\n\\*Encore Cloud Hosting is free to use, subject to Fair Use guidelines and usage limits. [Learn more](/docs/platform/management/usage)\n\n## Development Infrastructure\n\nEncore Cloud provisions infrastructure resources differently for each type of development environment.\n\n| | Local | Preview / Development (Encore Cloud Hosting) | GCP / AWS |\n| ------------------- | --------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |\n| **SQL Databases:** | Docker | Encore Cloud Managed (Kubernetes), [Neon](/docs/deploy/neon) | [See production](/docs/deploy/infra#production-infrastructure) |\n| **Pub/Sub:** | In-memory ([NSQ](https://nsq.io)) | GCP Pub/Sub | [See production](/docs/deploy/infra#production-infrastructure) |\n| **Caches:** | In-memory (Redis) | In-memory (Redis) | [See production](/docs/deploy/infra#production-infrastructure) |\n| **Cron Jobs:** | Disabled | [Encore Cloud Managed](/docs/primitives/cron-jobs) | [See production](/docs/deploy/infra#production-infrastructure) |\n| **Object Storage:** | Local Disk | Encore Cloud Managed | [See production](/docs/deploy/infra#production-infrastructure) |\n\n\n### Local Development\n\nFor local development Encore Cloud provisions a combination of Docker and in-memory infrastructure components.\nSQL Databases are provisioned using [Docker](https://docker.com). For Pub/Sub\nand Caching the infrastructure is run in-memory.\n\nWhen running tests, a separate SQL Database cluster is provisioned that is optimized for high performance\n(using an in-memory filesystem and fsync disabled) at the expense of reduced reliability.\n\nTo avoid surprises during development, Cron Jobs are not triggered in local environments.\nThey can always be triggered manually by calling the API directly from the [development dashboard](/docs/ts/observability/dev-dash).\n\nThe application code itself is compiled and run natively on your machine (without Docker).\n\n### Preview Environments\n\nWhen you've [connected your application to GitHub](/docs/platform/integrations/github), Encore Cloud automatically provisions a temporary [Preview Environment](/docs/platform/deploy/preview-environments) for each Pull Request.\n\nPreview Environments are created in Encore Cloud Hosting, and are optimized for provisioning speed and cost-effectiveness.\nThe Preview Environment is automatically destroyed when the Pull Request is merged or closed.\n\nPreview Environments are named after the pull request, so PR #72 will create an environment named `pr:72`.\n\n### Encore Cloud Hosting\n\nEncore Cloud Hosting is a simple, zero-configuration hosting solution provided by Encore.\nIt's perfect for development environments and small-scale use that do not require any specific SLAs.\nIt's also a great way to evaluate Encore Cloud without needing to connect your cloud account.\n\nEncore Cloud Hosting is not designed for business-critical use and does not offer reliability guarantees for persistent storage\nlike SQL Databases. Other infrastructure primitives like Pub/Sub and Caching\nare provisioned with small-scale use in mind.\n\n[Learn more about the usage limitations](/docs/platform/management/usage)\n\n## Production Infrastructure\n\nEncore Cloud provisions production infrastructure resources using best-practice guidelines and services for each respective cloud provider.\n\n| | GCP | AWS |\n| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| **Networking:** | [VPC](/docs/platform/infrastructure/gcp#networking-architecture) | [VPC](/docs/platform/infrastructure/aws#networking-architecture) |\n| **Compute:** | [Cloud Run](/docs/platform/infrastructure/gcp#google-cloud-run), [GKE](/docs/platform/infrastructure/gcp#google-kubernetes-engine) | [Fargate ECS](/docs/platform/infrastructure/aws#aws-fargate), [EKS](/docs/platform/infrastructure/aws#aws-eks) |\n| **SQL Databases:** | [GCP Cloud SQL](/docs/platform/infrastructure/gcp#databases), [Neon](/docs/platform/infrastructure/neon) | [Amazon RDS](/docs/platform/infrastructure/aws#databases), [Neon](/docs/platform/infrastructure/neon) |\n| **Pub/Sub:** | [GCP Pub/Sub](/docs/platform/infrastructure/gcp#pubsub) | [Amazon SQS & Amazon SNS](/docs/platform/infrastructure/aws#pubsub) |\n| **Object Storage:** | [GCS/Cloud CDN](/docs/platform/infrastructure/gcp#object-storage) | [Amazon S3/CloudFront](/docs/platform/infrastructure/aws#object-storage) |\n| **Caches:** | [GCP Memorystore (Redis)](/docs/platform/infrastructure/gcp#caching) | [Amazon ElastiCache (Redis)](/docs/platform/infrastructure/aws#caching) |\n| **Cron Jobs:** | Encore Cloud Managed | Encore Cloud Managed | Encore Cloud Managed |\n| **Secrets:** | [Secret Manager](/docs/platform/infrastructure/gcp#secrets-management) | [AWS Secrets Manager](/docs/platform/infrastructure/aws#se) |\n\n### Configuration\n\nWith Encore you do not define any cloud service specifics in the application code. This means that after deploying, you can safely use your cloud provider's console to modify the provisioned resources, or use the built-in configuration UI in the Encore Cloud dashboard.\n\nLearn more in the [Infrastructure Configuration](/docs/platform/infrastructure/configuration) documentation."
},
{
"path": "docs/platform/infrastructure/kubernetes.md",
"content": "---\nseotitle: How to deploy your Encore application to a new Kubernetes cluster\nseodesc: Learn how to automatically deploy your Encore application to a new Kubernetes cluster.\ntitle: Kubernetes deployment\nsubtitle: Deploying your app to a new Kubernetes cluster\nlang: platform\n---\n\n# Deploying Encore Apps to Kubernetes\n\nEncore Cloud gives you flexibility in where you run your applications. You have two options for Kubernetes deployments:\n\n1. **Deploy to a new cluster**: Encore Cloud can automatically provision and manage a new Kubernetes cluster in your cloud account on AWS or GCP.\n2. **Use an existing cluster**: Deploy to your pre-existing Kubernetes cluster ([see instructions here](/docs/platform/infrastructure/import-kubernetes-cluster))\n\nAll infrastructure provisioning is automated, and configuration is managed through the [Encore Cloud Dashboard](https://app.encore.cloud), keeping your application code clean and infrastructure-agnostic.\n\n## Deploying to a new Kubernetes cluster\n\n**1. Connect your cloud account:** Ensure your cloud account (Google Cloud Platform or AWS) is connected to Encore Cloud. ([See docs](/docs/platform/deploy/own-cloud))\n\n**2. Create environment:** Open your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to **Environments**, then click on **Create Environment**.\n\nNext, select your cloud (AWS or GCP) and then specify Kubernetes as the compute platform. Encore Cloud supports deploying to GKE on GCP, and EKS Fargate on AWS.\n\nYou can also configure if you want to allocate all services in one process or run one process per service.\n\n![](\"/assets/docs/k8s-config.jpg\" "\\"Environment")
\n\n**3. Push your code:** To deploy, commit and push your code to the branch you configured as the deployment trigger. You can also trigger a manual deploy from the Cloud Dashboard by going to the **Environment Overview** page and clicking on **Deploy**.\n\n**4. Automatic deployment by Encore Cloud:** Once you've triggered the deploy, Encore Cloud will automatically provision and deploy the necessary infrastructure on Kubernetes, per your environment configuration in the Cloud Dashboard. You can monitor the status of your deploy and view your environment's details through the Encore Cloud Dashboard.\n\n**5. Accessing your cluster with kubectl:** You can access your cluster using the `kubectl` CLI tool. [See the docs](/docs/platform/infrastructure/configure-kubectl) for how to do this.\n\n## Infrastructure Overview\n\nEncore Cloud simplifies the process of deploying applications by automatically provisioning and managing the necessary Kubernetes components. Here's an overview of the components Encore Cloud manages and how they work together to support your applications.\n\n### Namespace Management\n\nEncore Cloud creates a unique namespace for each environment deployed to your Kubernetes cluster, ensuring complete isolation between different environments of your application.\n\n### Secrets Management\n\nEncore Cloud provides comprehensive secrets management through deep integration with Kubernetes Secrets. Application secrets that you configure in Encore Cloud are automatically stored as Kubernetes Secrets and made available to your services at runtime. This includes both application-specific secrets that you define, as well as infrastructure secrets like database credentials that Encore Cloud manages automatically.\n\nService accounts are automatically bound to the appropriate secrets they need access to, ensuring each service can only access the secrets it requires. This follows the principle of least privilege and helps maintain a strong security posture.\n\n### Ingress Configuration\n\nEncore Cloud provisions and manages ingress for your applications through a cloud provider-specific ingress controller. The ingress controller is automatically configured to handle incoming traffic and route it securely to your application's Encore Gateway service. It manages TLS certificates automatically to ensure all traffic is encrypted, and provides fine-grained control over which services are accessible from the public internet. The controller configuration is optimized for your specific cloud provider to ensure the best possible performance and reliability.\n\n## Service Management\n\n### Deployments\nEncore Cloud manages the deployment configuration for each service in your application. Each service is deployed as a separate Kubernetes deployment, allowing for independent scaling and management. The deployment configurations are automatically generated and optimized based on your service's requirements.\n\nFor each service, Encore Cloud configures the pod specifications with appropriate resource requests and limits, health checks, and container settings. Runtime configurations like environment variables and command arguments are automatically set based on your application's needs. The container orchestration is handled seamlessly, with Encore Cloud managing pod scheduling, updates, and scaling to ensure your services run reliably and efficiently.\n\n### Network Configuration\n\nEncore Cloud provides a comprehensive networking setup through Kubernetes Service resources. Each service in your application gets assigned a unique cluster IP address, enabling reliable internal communication between services. This IP allocation works in conjunction with Kubernetes' built-in service discovery mechanism, allowing services to locate and communicate with each other using consistent internal DNS names. The internal service routing ensures that requests are efficiently distributed across all available pods for each service, providing automatic load balancing and failover capabilities.\n\n### Identity and Access\n\nEncore Cloud provides comprehensive service identity management through Kubernetes service accounts. Each pod is assigned its own dedicated service account, which handles authentication with the Kubernetes API and enables secure access to resources. These service accounts are automatically bound to the specific secrets and permissions required by each service.\n\nFor cloud provider integration, Encore Cloud maps the service accounts to appropriate IAM roles, enabling secure access to cloud resources like databases and object storage. Following the principle of least privilege, Encore Cloud configures the minimum required permissions for each service account, ensuring services can only access the resources they explicitly need.\n\nAll these configurations are automatically maintained and updated by Encore Cloud as you develop your application, ensuring your infrastructure stays aligned with your application's needs."
},
{
"path": "docs/platform/infrastructure/manage-db-users.md",
"content": "---\nseotitle: Managing database user credentials\nseodesc: Learn how to manage user credentials for databases created by Encore.\ntitle: Managing database user credentials\nlang: platform\n---\n\nEncore Cloud provisions your databases automatically, meaning you don't need to manually create database users. However, in some use cases you need access to the database user credentials, so Encore Cloud makes it simple to view them.\n\nAs an application **Admin**, open the [Encore Cloud dashboard](https://app.encore.cloud) and go to the **Infrastructure** page for the relevant environment.\n\nIn the section for the relevant **Database Cluster**, you will find a **Users** sub-section which lists your database users. Click on the \"eye\" icon next to each username to decrypt the password.\n\nNote that databases hosted in [Encore Cloud](/docs/platform/infrastructure/infra#encore-cloud) currently do not expose usernames and passwords.\nTo connect to an Encore Cloud-hosted database, use [`encore db shell`](/docs/ts/primitives/databases#connecting-to-databases).\n\n`encore db shell` defaults to read-only permissions. Use `--write`, `--admin` and `--superuser` flags to modify which permissions you connect with.\n\n![](\"/assets/docs/db-user.png\" "\\"View")
\n\n![](\"/assets/docs/connect-neon.png\" "\\"Connect")
\n\n## Creating environments using Neon\nNeon organizes databases in projects. A project consist of a main branch and any number of feature branches.\n[Branches](https://neon.tech/docs/introduction/branching) in Neon are similar to branches in git, letting you to create a new branch for each feature or bug fix, to test your changes in isolation.\n\nWhen configuring your Encore Cloud environment to use Neon, you can choose which project and branch to use. To get started,\nhead to the [Encore Cloud dashboard](https://app.encore.cloud) > (Select your app) > Environments > Create Environment. In the Database section, select\n`Neon database`.\n\n![](\"/assets/docs/create-neon.png\" "\\"Create")
\n\n### Create a new Neon project and branch\nIf you're starting off a blank slate, you can let Encore Cloud create a new Neon project and branch for you.\nSelect `New Neon project` and choose a Neon account and region. We recommend picking a region close to your compute and\nthat you use the suggested project and branch names, but you're free to choose any configuration you like.\n\n### Branch from an existing Encore Cloud environment\nIf you already have an Encore Cloud environment with Neon, you can branch your database from that environment.\nSimply select `Branch from Encore environment` and choose the environment you want to branch from. This option will\nbe disabled if you don't have any environments using Neon.\n\n### Branch from an existing Neon branch\nYou can also choose to manually select a Neon branch to branch from. This is useful if you have an existing Neon project,\nbut it's not currently being used by any Encore Cloud environments. Select `Branch from Neon project`,\nthen choose the account, project and branch you want to use.\n\n### Import an existing Neon branch\nThe final option is to import an existing Neon branch. This is useful if you have an existing database you want to use.\nBe wary that this option will not create a new branch but operate on the existing data. Select `Import Neon branch`,\nthen choose the account, project and branch you want to use.\n\n**Note:** You may need to manually adjust the roles, commonly you need to change the database owner to the `db_![](\"/assets/docs/edit-neon.png\" "\\"Edit")
\n\n### Neon project\nThe retention history specifies how long Neon will keep changes to your data. The default is 1 day, but depending on your\nNeon plan, you can increase this to up to 30 days.\n\n### Neon endpoint\nEach branch is assigned a unique endpoint which essentially is the serverless compute handling your database.\nYou can edit the endpoint to set the CPU limits and the suspend timeout. The suspend timeout is the time Neon will wait\nbefore suspending the compute when it's not in use. The default is 5 minutes, but you can increase this to up to a week\n(depending on your Neon plan).\n\n## Use Neon for Preview Environments\nNeon is a great choice for [Preview Environments](/docs/platform/deploy/preview-environments) as it allows you to branch off a populated\ndatabase and test your changes in isolation.\n\nTo configure which branch to use for Preview Environments, head to the\n[Encore Cloud dashboard](https://app.encore.cloud) > (Select your app) > App Settings > Preview Environments\nand select the environment with the database you want to branch from. Hit save and you're all done.\n\nKeep in mind that you can only branch from environments that use Neon as the database provider; this is the default for Encore Cloud environments, but is a configurable option when creating AWS and GCP environments.\n\n![](\"/assets/docs/customdomain.png\" "\\"Custom")
\n\n![](\"/assets/img/git-connect.png\")
\n\nWhen you come back to Encore, click the **Link App to GitHub** button:\n\n![](\"/assets/img/git-begin.png\")
\n\nIn the popup, select the repository you would like to link your app with:\n\n![](\"/assets/img/git-modal.png\")
\n\nClick **Link** and you're done! Encore will now automatically start building and running tests against\nyour Pull Requests, and provision Preview Environments for each Pull Request.\n\n![](\"/assets/img/git-linked.png\")
\n\n## Placing your Encore app in a monorepo sub-folder\n\nIf you already have a monorepo and want to place your Encore application in a sub-folder, you need to tell Encore which folder the `encore.app` file is in.\n\nDo this by opening your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to **Settings** > **General**. Then in the **Root Directory** section, you specify the directory within your Git repository in which your `encore.app` file is located.\n\n## Configure deploy trigger\n\nWhen using GitHub, you can configure Encore to automatically trigger deploys when you push to a specific branch name.\nTo configure which branch name is used to trigger deploys, open your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the `Branch name` and hit save.\n\n## Preview Environments for each Pull Request\n\nOnce you've linked your app with GitHub, Encore will automatically start building and running tests against\nyour Pull Requests.\n\nEncore will also provision a dedicated Preview Environment for each pull request.\nThis environment works just like a regular development environment, and lets you test your changes\nbefore merging.\n\nLearn more in the [Preview Environments documentation](/docs/platform/deploy/preview-environments).\n\n![Preview environment linked in GitHub](/assets/docs/ghpreviewenv.png \"Preview environment linked in GitHub\")\n"
},
{
"path": "docs/platform/integrations/oauth-clients.md",
"content": "---\nseotitle: Encore Cloud OAuth Clients\nseodesc: Learn how to use OAuth Clients for access to the Encore Cloud API\ntitle: OAuth Clients\nlang: platform\n---\n\nOAuth clients provide a framework for delegated and scoped access to the Encore Cloud API. An OAuth client creates short-lived access tokens on demand, and supports the principle of least privilege by allowing fine-grained control on the access granted to the client using scopes.\n\n## How it works\nYou create an OAuth client that defines the scopes to allow when your client application uses the Encore Cloud API.\n\nScopes are currently grouped into \"roles\", which include a set of permissions.\nFor example, the `deployer` role grants access to the triggering deployments.\n\nAn OAuth client consists of a client ID and a client secret. When you create an OAuth client, Encore Cloud creates these for you. Within your client application, use the client ID and client secret to request an API access token from the Encore Cloud's OAuth token endpoint. You use the access token to make calls to the Encore Cloud API. The access token grants permission only for the scopes that were defined when you created the OAuth client.\n\nAn API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from Encore Cloud's OAuth token endpoint.\n\nOAuth client libraries in popular programming languages can handle the API access token generation and renewal.\n\nEncore Cloud's OAuth implementation is based on the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749).\n\n## Prerequisites\nYou need to be an Owner of the Encore application in order to create or revoke OAuth clients.\n\n### Setting up an OAuth client\nOpen the OAuth clients page in the application settings page.\n\nIn the Generate OAuth client dialog, select the set of operations that can be performed with tokens created by the new OAuth client.\n\nAfter generating the client, you can see the new OAuth client's ID and secret. Copy both the client ID and secret, as you need them for your client code.\nNote that after you close the Generated new OAuth client dialog, you won't be able to copy the secret again.\n**Store the client secret securely.**\n\nYour OAuth client is now configured. Use the client ID and secret when you configure your OAuth client application. Note that the provided client secrets are case-sensitive.\n\nIf an OAuth client is created by a user who is later removed from your application, the OAuth client will continue to function and generate API access tokens.\nApplication owners can see all configured OAuth clients in the OAuth clients page of the application settings.\n\n### Roles\nRoles define which operations are permitted in API access tokens that are created by your client application.\n\nCurrently there is a single supported role: **Deployer**. The deployer role\nallows for programatically triggering deployments.\n\nWhen new Encore Cloud functionality is provided, we will add it to existing roles where applicable.\nThat means a role is not restricted to only access of APIs that existed at the time the client was initially authorized — a role will contain additional access where it makes sense for new or updated functionality.\n\n### Revoking an OAuth client\nOpen the OAuth clients page of the application settings page.\n\nFind the OAuth client that you want to delete and select Revoke.\n\nSelect Revoke OAuth client to confirm you want to revoke the OAuth client.\n\nWhen you revoke an OAuth client, any active API access tokens that were created by the client are also revoked.\n\n### Encore Cloud OAuth token endpoint\nEncore Cloud's OAuth token endpoint is https://api.encore.cloud/api/oauth/token.\nSee the [Encore Cloud API Reference](/docs/platform/integrations/api-reference) documentation for more information.\n\nMake requests to the OAuth token endpoint when you need an API access token. The OAuth token endpoint accepts requests that conform to the OAuth 2.0 client credentials grant request format, and returns responses that conform to the OAuth 2.0 client credentials grant response format.\n\n## OAuth client libraries\nPopular programming languages provide OAuth client libraries to simplify your use of OAuth clients.\n\nFor example, the following Go code shows how to create an OAuth client object that uses your client ID and client secret to generate an API access token for calls to the Encore Cloud API.\nSimilar libraries exist for other popular programming languages.\n\n```go\npackage main\n\nimport (\n \"context\"\n \"os\"\n\n \"golang.org/x/oauth2/clientcredentials\"\n)\n\nfunc main() {\n oauthConfig := &clientcredentials.Config{\n ClientID: os.Getenv(\"OAUTH_CLIENT_ID\"),\n ClientSecret: os.Getenv(\"OAUTH_CLIENT_SECRET\"),\n TokenURL: \"https://api.encore.cloud/api/oauth/token\",\n }\n\n client := oauthConfig.Client(context.Background())\n\n // Make API calls using `client.Get` etc.\n resp, err := client.Get(\"https://api.encore.cloud.com/api/...\")\n // ...\n}\n```\n\nThe example requires that you define environment variables `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`, with their values set to the client ID and client secret that are created when you set up an OAuth client.\n\n### Verifying you can generate API access tokens\nAfter you set up an OAuth client, an easy way to confirm that you can generate API access tokens is to make a curl request to the Encore Cloud OAuth token endpoint.\n\n\n```bash\ncurl -d \"client_id=${OAUTH_CLIENT_ID}\" -d \"client_secret=${OAUTH_CLIENT_SECRET}\" \\\n -d \"grant_type=client_credentials\" \"https://api.encore.cloud/api/oauth/token\"\n```\n\nThe example requires that you define environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, with their values set to your client ID and client secret.\n\nHere's an example response showing the API access token:\n\n```json\n{\"access_token\":\"MTcyODQ3NTg3NXww...GDxfmxnuq9zDEAmHmP5D44=\",\"token_type\":\"Bearer\",\"expires_in\":3600, \"actor\": \"o2c_my_key_id\"}\n```\n\n## Limitations\n\nAn OAuth access token expires after 1 hour — this duration cannot be modified.\n"
},
{
"path": "docs/platform/integrations/terraform.md",
"content": "---\nseotitle: Integrate Encore with existing infrastructure\nseodesc: The Encore Terraform Provider lets you integrate your Encore deployment with existing infrastructure\ntitle: Terraform Provider\nsubtitle: Integrate Encore with existing infrastructure\ninfobox: {\n title: \"Terraform Provider\",\n import: \"https://registry.terraform.io/providers/encoredev/encore\",\n}\nlang: platform\n---\nEncore makes it simple to deploy and manage cloud applications. When you're dealing with a large and complex system, you may want to integrate Encore-provisioned resources with an existing infrastructure landscape. For this purpose, Encore maintains a Terraform Provider with data sources for all Encore-provisioned resources.\n\n## Understanding Encore Terraform Data Sources\n\nEncore Terraform data sources act as read-only references to resources Encore has already provisioned on your behalf.\nUnlike Terraform resources (which create or modify infrastructure), data sources only retrieve information. The Encore\ndata sources let's you retrieve cloud identifiers for resources managed by Encore, such as databases, caches, and more.\nTo do this, you only need to provide the name of the resource and the environment it's in.\n\n## Configuring the Encore Terraform Provider\n\nTo use Encore data sources, you need to declare the Encore Terraform provider in the `required_providers` of\nyour Terraform configuration file. Here's an example of how to declare the provider:\n\n```\nterraform {\n required_providers {\n encore = {\n source = \"registry.terraform.io/encoredev/encore\"\n }\n }\n}\n```\n\nOnce you've declared the provider, Terraform will automatically download the provider plugin when initializing the\nworking directory using `terraform init`.\n\nTo authenticate with the Encore API, the provider need an Encore Auth Key. You can generate an auth key from\nEncore's [Cloud Dashboard](https://encore.dev/docs/platform/integrations/auth-keys). Once you have the auth key, you can configure the\nprovider in your Terraform configuration file like this:\n\n```\nprovider \"encore\" {\n env = \"your-env\"\n auth_key = \"your-auth-key\"\n}\n```\nYou can also set the `ENCORE_AUTH_KEY` environment variable to avoid hardcoding the auth key in your configuration file.\n\n## Using Encore Terraform Data Sources\n\nOnce you have the provider configured, you can use the Encore data sources to retrieve information about resources.\nThere are several data sources available, such as `encore_database`, `encore_cache`, and `encore_pubsub_topic`. Each data\nsource has its own set of attributes that you can use to retrieve information about the resource. The full documentation\nfor each data source is available in the [Terraform Registry](https://registry.terraform.io/providers/encoredev/encore).\n\nHere's an example of how to use the `encore_pubsub_topic` data source to connect AWS IOT Core to an Encore PubSub topic:\n\n```\ndata \"encore_pubsub_topic\" \"topic\" {\n name = \"my-topic\"\n env = \"my-env\"\n}\n\nresource \"aws_iot_topic_rule\" \"rule\" {\n name = \"my-rule\"\n sql = \"SELECT * FROM 'my-topic'\"\n sns {\n message_format = \"RAW\"\n role_arn = aws_iam_role.role.arn\n target_arn = data.encore_pubsub_topic.topic.aws_sns.arn\n }\n}\n```\n"
},
{
"path": "docs/platform/integrations/webhooks.md",
"content": "---\nseotitle: Subscribe to Encore Cloud webhooks and events\nseodesc: Encore Cloud lets you define webhooks to react to events in your application, enabling you to build powerful integrations.\ntitle: Webhooks & Events\nsubtitle: Set up webhooks to react to Encore events\ninfobox: {\n title: \"Webhooks\",\n import: \"go.encore.dev/webhooks\",\n}\nlang: platform\n---\n\nWebhooks provide a way for notifications to be delivered to an HTTP endpoint of your choice whenever certain events happen within Encore.\nFor example, you can set up a webhook to be notified whenever a deployment starts or finishes.\n\nWebhooks are defined on a per-application basis, and are configured under Settings -> Webhooks in the [Encore Cloud dashboard](https://app.encore.cloud).\n\nTo simplify using webhooks, Encore.go provides a Go module, [go.encore.dev/webhooks](https://pkg.go.dev/go.encore.dev/webhooks), that provides\ntype definitions and documentation of all supported webhook events. This module is kept up to date as new events are added.\n\n## Webhook Deliveries\n\nEach time an event occurs that matches one of your defined webhooks,\nEncore will send a HTTP POST request to the webhook's configured URL with information about the event.\n\nIf the HTTP request fails, the delivery is marked as failed and won't be retried.\n\nEach event is given a unique event id, which is shared across all webhooks.\n\nWithin each webhook, each event is given a sequence number, which is incremented for each event\nthat matches that webhook. The sequence number allows for a linear ordering of events within a webhook,\nmaking it easy to determine if an event was missed.\n\nThese are provided in the `X-Encore-Event-Id` and `X-Encore-Sequence-Id` headers respectively,\nand are also part of the event payload itself.\n\n## Parsing webhook events\n\nTo parse a webhook event, use the [`webhooks.ParseEvent`](https://pkg.go.dev/go.encore.dev/webhooks#ParseEvent) function.\n\nAs you'll see in the example below, to parse the webhook event you'll need access to the webhook secret.\nThis is a secret value that is generated by Encore and is used to sign each webhook request. More about this\nin the next section.\n\nFor example, to process rollout started and completed webhook events,\nyou could do something like this:\n\n```go\npackage service\n\nimport (\n \"net/http\"\n\n \"go.encore.dev/webhooks\"\n)\n\nvar secrets struct {\n\tEncoreWebhookSecret string\n}\n\n//encore:api public raw\nfunc Webhook(w http.ResponseWriter, req *http.Request) {\n\tpayload, err := io.ReadAll(req.Body)\n\tif err != nil {\n\t\t// ... handle error\n }\n event, err := webhooks.ParseEvent(payload, req.Header.Get(\"X-Encore-Signature\"), secrets.EncoreWebhookSecret)\n if err != nil {\n // ... handle error\n }\n\n switch data := event.Data.(type) {\n case *webhooks.RolloutCreatedEvent:\n // ... handle rollout created event\n case *webhooks.RolloutCompletedEvent:\n // ... handle rollout completed event\n }\n}\n```\n\n![](\"/assets/docs/arch_full.png\" "\\"Encore")
\n\nEncore Cloud's core functionality is enabled by Encore's open source backend frameworks, [Encore.ts](/docs/ts) and [Encore.go](/docs/go). These frameworks let you define essential backend resources – like APIs, microservices, databases, cron jobs, and Pub/Sub – as type-safe objects in your code using simple, declarative syntax.\n\nThe frameworks have a minimal footprint, where one line of code is enough to define a backend resource, and are designed to be unobtrusive, so that you can focus on building your product without being distracted by the underlying infrastructure.\n\nWith the backend frameworks you only define **infrastructure semantics** — _the things that matter to your application's behavior_ — not configuration for _specific_ cloud services. Encore Cloud then automatically generates boilerplate and orchestrates the relevant infrastructure for each environment using your cloud provider's API or directly through Encore Cloud's built-in cloud hosting for development.\n\n![](\"/assets/docs/arch_local.png\" "\\"Encore's")
\n\nThe local development tooling is fully open source. When you run your app locally using the [Encore CLI](/docs/ts/install), it parses your code and automatically sets up the necessary local infrastructure on the fly. _No more messing around with Docker Compose!_\n\nAside from managing infrastructure, Encore's local development workflow comes with a lot of tools to make building distributed systems easier:\n\n- **Local environment matches cloud:** Encore automatically handles the semantics of service communication and interfacing with different types of infrastructure services, so that the local environment is a 1:1 representation of your cloud environment.\n- **Cross-service type-safety:** When building microservices applications with Encore, you get type-safety and auto-complete in your IDE when making cross-service API calls.\n- **Type-aware infrastructure:** With Encore, infrastructure like Pub/Sub queues are type-aware objects in your program. This enables full end-to-end type-safety when building event-driven applications.\n- **Tracing:** The [local development dashboard](/docs/ts/observability/dev-dash) provides local tracing to help understand application behavior and find bugs.\n- **Automatic API docs & clients:** Encore generates [API docs](/docs/ts/observability/service-catalog) and [API clients](/docs/ts/cli/client-generation) in Go, TypeScript, JavaScript, and OpenAPI specification.\n\n## Testing\n\n![](\"/assets/docs/arch_testing.png\" "\\"Encore's")
\n\nEncore's open source framework comes with several built-in tools to help with testing:\n\n- **Built-in service/API mocking:** Encore provides built-in support for [mocking API calls](/docs/go/develop/testing/mocking), and interfaces for automatically generating mock objects for your services.\n- **Local test infra:** When running tests locally, Encore automatically provides dedicated [test infrastructure](/docs/go/develop/testing#test-only-infrastructure) to isolate individual tests.\n- **Local test tracing:** The [Local Development Dashboard](/docs/go/observability/dev-dash) provides distributed tracing for tests, providing great visibility into what's happening and making it easier to understand why a test failed.\n\nEncore Cloud adds to this tool-set with:\n- **Preview Environments:** Encore automatically provisions a [Preview Environment](/docs/platform/deploy/preview-environments) for each Pull Request, an effective tool when doing end-to-end testing.\n\n## Infrastructure & DevOps automation\n\n![](\"/assets/docs/arch_devops.png\" "\\"Encore's")
\n\n### Infrastructure Management\n- **Zero-config deployment:** Connect your repo and cloud account, then deploy and Encore Cloud orchestrates your cloud resources by integrating with your cloud provider's API.\n- **Automatic infrastructure:** Use battle-tested AWS/GCP services (Cloud Run/Fargate, GKE/EKS, CloudSQL/RDS, Pub/Sub / SQS/SNS, etc.) without any manual setup or configuration.\n- **No IaC required:** Say goodbye to Terraform and YAML - your code is the single source of truth.\n\n### Security & Governance\n- **Automated IAM:** Least-privilege security permissions generated from parsing your code\n- **Infrastructure tracking:** Complete visibility of all provisioned resources\n- **Change management:** Built-in approval workflow for infrastructure changes\n- **Configuration management:** Simple UI for config changes that automatically 2-way syncs to your cloud\n\n### Monitoring & Observability\n- **Cost monitoring:** Track infrastructure costs across your cloud resources (currently for GCP, AWS coming soon)\n- **Integrated observability:** Built-in logging, metrics, and tracing\n- **Third-party integration:** Works with Datadog, Grafana, and other tools\n- **Auto-generated documentation:**\n - Service catalog with complete API docs\n - Live architecture diagrams showing infrastructure dependencies\n\n## Why choose Encore Cloud?\n\nEncore Cloud's end-to-end workflow is an unfair advantage for teams that need to move quickly without sacrificing quality and scalability.\nBy automating over 90% of the normal day-to-day DevOps work, you can focus on building your product instead of building your own developer platform.\n\nThe benefits of Encore Cloud are:\n\n- **Faster Development**: Encore Cloud enables 2-3x faster iterations thanks to the streamlined the development process with its clear abstractions and built-in development tools.\n- **Reduced Costs**: Encore Cloud's infrastructure management minimizes wasteful cloud expenses and reduces DevOps workload by 90%.\n- **Scalability & Performance**: Encore Cloud simplifies building microservices applications that can handle growing user bases and demands, without the normal boilerplate and complexity.\n- **Control & Standardization**: Encore Cloud enforces standardization and provisions infrastructure consistently according to best practices for each cloud provider.\n- **Quality through understandability:** Built-in tools like automated architecture diagrams, generated API docs, and distributed tracing make it simple for teams to get an overview of their system and ensure the correct behavior.\n- **Security**: Encore Cloud makes your application secure by automatically implementing security best practices for each cloud provider.\n\n## Common use cases\n\nEncore Cloud is designed to give teams a productive and less complex experience when solving most common backend use cases.\nMany teams use Encore Cloud to build things like:\n\n- Consumer apps\n- High-performance B2B Platforms\n- Fintech & Crypto applications\n- Global E-commerce marketplaces\n- Microservices backends and event-driven systems for scalable SaaS applications\n- And much more...\n\nCheck out the [showcase](https://encore.cloud/showcase) section for some examples of real-world products being built with Encore.\n\n## Getting started\n\n- [Follow the Quick Start Guide](/docs/ts/quick-start)\n- [Join Discord](https://encore.dev/discord) to ask questions and meet other Encore developers\n- Follow and star the project on [GitHub](https://github.com/encoredev/encore) to stay up to date\n- [Book a demo](https://encore.dev/book) to speak to one of our founders about if Encore Cloud is a good fit for your team\n"
},
{
"path": "docs/platform/management/billing.md",
"content": "---\nseotitle: Plans & Billing\nseodesc: Encore is free to use for many projects, and comes with paid plans for teams who want to move quickly. Learn more!\ntitle: Plans & Billing\nsubtitle:\nlang: platform\n---\n\nEncore offers a **Free** plan for teams that want a simple development workflow and collaboration features.\nIf you want access to all features and want to use Encore's DevOps automation tools for AWS & GCP, there's a paid **Pro** plan available.\n\nSee the [pricing page](https://encore.dev/pricing) for a feature comparison between each plan and complete pricing information.\n\n## When do I need to upgrade to a paid plan?\n\nThe Free plan comes with certain limitations, and should your needs exceed one or more of them, you may wish to upgrade to a paid plan:\n\n- When you need more than 2 cloud environments\n- When you want to [automate DevOps in your cloud on AWS/GCP](/docs/platform/infrastructure/infra)\n- When you want [Preview Environments](/docs/platform/deploy/preview-environments) for each Pull Request\n- When you want to use a Custom Domain\n- When you need multiple concurrent builds\n- When you need guaranteed logs & tracing retention\n- When you want access to private support & onboarding assistance\n- When you want custom configuration for environments hosted on Encore Cloud\n\nThere is a free 14-day trial of the Pro plan, available to all new Encore users. It's a great way to try out all the features and learn if the Pro plan suits your needs.\nYou can activate your trial from the [pricing page](https://encore.dev/pricing).\n\n## Do I need to pay for hosting?\n\nAll plans come with free use of Encore Cloud, subject to [Fair Use limits](/docs/platform/management/usage).\nEncore Cloud is intended for development environments and limited scale professional use that does not require specific SLAs.\n\nFor production use, you can [connect your own cloud account on AWS/GCP](/docs/platform/deploy/own-cloud) and use Encore to deploy there, including provisioning infrastructure and managing IAM. When you connect your own cloud account, you pay for usage directly to your cloud provider.\n\nIf you prefer to manage deployment yourself, you can export your application as a standalone Docker image and deploy in any way you prefer. ([Learn more](/docs/ts/self-host/build))\n\n## Payments & Billing FAQ\n\n### What is the price of the paid plan?\n\nSee the [pricing page](https://encore.dev/pricing) for complete pricing information.\n\nIf you are a large organization with specific needs, please [email us](mailto:hello@encore.dev) or [book a 1:1](/book) to discuss your needs and get a custom price quote.\n\n### Can I pay with a credit card?\n\nYes, we offer payments via Stripe using all major credit cards. You can upgrade your account via the [pricing page](/pricing).\n\n### What happens if my payment fails?\n\nIf your payment fails, everything will keep working as normal!\nWe will reach out to you with instructions on how to update your payment information so that we can try to process your payment again.\nWe will not downgrade your account without prior notice.\n"
},
{
"path": "docs/platform/management/compliance.md",
"content": "---\nseotitle: Security & Compliance\nseodesc: Learn about Encore's security practices, infrastructure protections, and compliance posture — built on industry-standard controls and trusted cloud providers.\ntitle: Security & Compliance\nsubtitle: How Encore protects your applications, code, and data\nlang: platform\n---\n\n_Last updated: March 3, 2026_\n\nYour applications, code, and data are among your most important assets. Security is foundational to everything we build at Encore — it is embedded in our architecture, our processes, and our culture. This document provides a comprehensive overview of the security controls and practices we have in place today, structured around the SOC 2 trust service criteria.\n\n### Security at a glance\n\n| Area | What we do |\n| --- | --- |\n| **Infrastructure** | Hosted on GCP (ISO 27001 / SOC 2 certified). All servers are private, accessible only via VPN. |\n| **Encryption** | AES-256 at rest, TLS 1.2+ and WireGuard in transit. Customer secrets additionally encrypted via GCP KMS. |\n| **Zero-trust networking** | All server-to-server communication is authenticated and end-to-end encrypted via Tailscale / WireGuard. |\n| **Access control** | Principle of least privilege, MFA enforced, regular access reviews, VPN-only infrastructure access. |\n| **Authentication** | Managed by Clerk (SOC 2 certified). Passwordless by default — Encore never stores or handles user passwords. |\n| **Monitoring & alerting** | 24/7 monitoring via Grafana, Sentry, Cronitor, and GCP Cloud Monitoring (all SOC 2 certified). |\n| **Vendor security** | All critical vendors are SOC 2 and/or ISO 27001 certified (GCP, Tailscale, Clerk, GitHub, Sentry, Grafana). |\n| **Code quality** | Mandatory code review, CI/CD with automated testing, automated vulnerability scanning. |\n| **Data privacy** | GDPR compliant. Data minimization by design. |\n| **Responsible disclosure** | Active bug bounty program for security researchers. |\n\n## SOC 2\n\nSOC is short for \"System and Organization Controls\" — it is the de facto industry standard for software security and privacy. We have implemented controls aligned with the SOC 2 framework and are currently preparing for a formal SOC 2 Type 1 audit, during which an external auditor will verify that our controls meet the standard.\n\nAfter the Type 1 audit, we plan to proceed to Type 2, which involves continuous monitoring over an extended period.\n\n### Trust Service Criteria\n\nThe five SOC 2 trust service criteria are: security, availability, confidentiality, processing integrity, and privacy.\n\n**1\\. Security**\n\nProtecting systems against unauthorized access.\n\n**2\\. Availability**\n\nEnsuring that the system remains functional and usable.\n\n**3\\. Confidentiality**\n\nRestricting the access of data to a specified set of persons or organizations. Ensuring that network communication is encrypted and cannot be intercepted by unauthorized personnel.\n\n**4\\. Processing integrity**\n\nEnsuring that a system fulfills its purpose and delivers correct data.\n\n**5\\. Privacy**\n\nMinimal processing and use of personal data in accordance with the law.\n\nThe following sections describe in detail how Encore implements each trust service principle.\n\n## Security\n\nWe believe security is achieved through proven best practices and industry standards — not through obscurity or homegrown cryptography. Our approach is defense in depth: multiple overlapping layers of protection so that the compromise of any single layer does not result in a breach.\n\nWe have a designated Security Officer responsible for all aspects of security across infrastructure, software, and data.\n\n### Infrastructure security\n\nEncore's core production infrastructure is hosted on GCP (Google Cloud Platform), an ISO27001/SOC 2 compliant vendor. Auxiliary services are provided by Hetzner, an ISO27001 compliant vendor. Tailscale, a SOC 2 compliant vendor, provides VPN (Virtual Private Network) services used to secure communication between all servers.\n\nAll core data processing is carried out in the US East region (us-east-1), and backups are kept in multiple separate regions in the US. Each region is composed of at least three \"availability zones\" (AZs) which are isolated locations, designed to take over in case of a catastrophic failure at one location. AZs are separated by a significant distance such that it is unlikely that they are affected by the same issues such as power outages, earthquakes, etc. Physical access to GCP is restricted by GCP's security controls. Furthermore, GCP monitors and immediately responds to power, temperature, fire, water leaks, etc.\n\nAccess to Encore's production infrastructure is restricted to Encore employees. All systems have access controls and only a limited number of employees have privileged access. Access is only possible through a VPN over Tailscale.\n\nThe production environment is separated from testing environments, using separate accounts and VPCs (Virtual Private Cloud) in GCP. This ensures that any defect in a test environment cannot impact the production system. The connection to the internet is controlled by dedicated gateways.\n\n### Organizational security\n\nAn organization is only as strong as its people. All employees undergo a rigorous selection process, and many of Encore's team members bring extensive experience from regulated environments such as online banking and large-scale payment systems.\n\nEmployees are required to complete annual security awareness training covering physical security, digital hygiene (strong passwords, two-factor authentication), social engineering (\"phishing\"), and related topics. Individual performance is reviewed on a bi-weekly cadence, and organizational performance is tracked via KPIs reviewed monthly by management.\n\nEncore employment policy mandates full-disk encryption on all employee devices.\n\n### Product security\n\nMultiple layers of protection ensure that customer data is not accessible to unauthorized persons.\n\nEncore's service-based architecture provides natural isolation between components, and we have adopted a zero-trust security model with Tailscale. All server-to-server communication is authenticated and end-to-end encrypted with WireGuard. GCP's VPC (Virtual Private Cloud) provides another layer of isolation from the internet on the network level. None of Encore's servers are publicly accessible on the internet.\n\nAs a general principle, all of Encore's data is encrypted while being transported across networks and when stored (\"in transit and at rest\"). In case of unauthorized access to the data, an attacker would only see undecipherable garbage which cannot be decrypted without the corresponding keys. The encryption methods employed by Encore are industry standard and deemed unbreakable by contemporary standards. Data at rest (virtual filesystems, relational databases, and object storage) is encrypted using GCP's industry-standard AES-256, while data in transit is encrypted with TLS ≥ 1.2 (for Encore's REST API) or WireGuard (for internal communication).\n\nAll customer secret information is further encrypted using GCP's Key Management Service (KMS). Any access to encrypted data by Encore employees requires elevated access and approval by multiple parties, and all such activity is audited.\n\nUser account authentication is provided by _Clerk_, a SOC 2 compliant vendor.\n\nThere are two ways for a user to log in to Encore: Single sign-on (SSO) and username plus password. Single sign-on can be used by organizations to fully manage access to Encore and, for example, ensure that former employees no longer have access after the offboarding period. Encore supports Google and GitHub SSO using OAuth.\n\nIf no SSO is used, the default login method is passwordless login using email and \"magic link\", also handled by _Clerk_. Encore does not store or in any way handle passwords, neither in plaintext nor cryptographic hash form. This means that Encore does not know the passwords of any users, and no passwords can be reconstructed from our databases.\n\nEncore uses automated vulnerability scanning across its codebase and dependencies. All teams continuously monitor their services for vulnerabilities and proactively remediate them, supervised by the Security Officer.\n\nAll security issues undergo a triaging process by the Security Officer and are escalated based on criticality.\n\n### Responsible disclosure\n\nWe maintain an active bug bounty program to encourage security researchers to report vulnerabilities before they can be exploited. If you discover a security issue, please report it to [security@encore.dev](mailto:security@encore.dev). We are committed to investigating all reports promptly and working with researchers to resolve issues responsibly.\n\n### Access control\n\nWe regularly keep track of and review the list of employees who have access to which systems and remove access where applicable to ensure least access principles apply.\n\nOffboarding processes ensure that former employees cannot access internal systems anymore after the termination of their contract. Thanks to the VPN, Encore can centrally restrict access to internal networks.\n\n#### MFA\n\nMulti-factor authentication (MFA) adds another layer of security on top of classic password authentication. In addition to username and password, the user requires another individual token of access.\n\nStealing or guessing the password is not enough for an attacker to gain access to a system, because the second factor would also need to be stolen.\n\nUsually, the second factor is a physical device, such as a mobile phone which has been paired with the authentication system. Encore employs MFA to protect access to the infrastructure provider (GCP) and the version control systems (GitHub), among other systems.\n\n## Availability\n\nHosted on a cloud infrastructure, Encore implements a service-based architecture where many dedicated software components operate isolated from one another, but in a coordinated way, much like a complex machine where individual parts can be replaced independently from one another.\n\nDuring the release of a new version of Encore services, Encore's engineers take great care during the preparation of the update so that in case of an unexpected problem, the system can be restored to the previous state in a manner that minimizes user impact.\n\n### Performance monitoring\n\nEncore uses a number of performance monitoring systems, such as Sentry, Cronitor, Grafana, and Google Cloud Monitoring (all being SOC 2 compliant vendors). Grafana is used to monitor application performance, such as server response times and user interface speed. Grafana also collects server-side metrics like CPU and RAM usage. Additionally, Encore monitors the performance of databases with GCP tooling.\n\nSlack, a SOC 2 compliant vendor, is used as the alerting channel to notify the developers in case the performance of the system has regressed, for example, due to increased response times, or increased error rates. To enable root cause analysis of bugs, Encore collects system logs from all parts of the system. These logs can only be accessed by authorized users.\n\nEncore offers a public \"Status page\" where users and customers can find the current status of Encore systems. It is available at: [https://status.encore.dev/](https://status.encore.dev/).\n\n### Backups and disaster recovery\n\nTo reduce the risk of simultaneous failure, Encore backs up data to multiple US regions in GCP, with very limited access. Relational databases are backed up on a daily schedule.\n\nEncore is currently planning a rehearsal of disaster recovery in Q4 of 2026. In this exercise, a clone of the production environment will be recovered from scratch using backups and tested for soundness.\n\n### Incident handling\n\nWhenever an incident occurs, Encore's designated on-call engineer initiates an investigation and escalates to the broader engineering team as necessary based on severity. For issues deemed critical, they follow an iterative response process to identify and contain errors, recover systems and services, and remediate vulnerabilities.\n\nCustomers and users can report outages via regular support channels (for example via email, or using the [Discord](https://encore.dev/discord) chat group). Encore's internal communication systems have dedicated channels for incident escalation.\n\n## Confidentiality\n\nWhen you use Encore, other users won't be able to see your content, unless you grant access explicitly by inviting them to your application. Encore engineers may use your data to provide support and when necessary to fix bugs.\n\n### Access controls\n\nAll employees and contractors are contractually bound to confidentiality, which persists after the termination of the work contract.\n\nAs part of a \"clean screen\" policy, all computers used by Encore staff must be set to automatically lock the screen after 1 minute of inactivity.\n\nAll systems access is subject to the \"principle of least privilege\", meaning that every employee only has access to the systems necessary to perform their official duties.\n\n### Deletion\n\nUser data will be stored by Encore after the termination of a subscription term, according to [Encore's Terms of Service](https://encore.cloud/legal/terms). When a user requests the deletion of data, the data is made inaccessible or physically deleted, depending on the data type and storage location. For technical reasons, data may remain in backups after this point.\n\n## Processing integrity\n\n### Quality assurance\n\nProduct quality is very important to Encore. There are many different facets, including:\n\n- Accuracy and usability of services provided\n\n- High performance of the user interface and Encore services\n\n- Almost zero downtime\n\nSeveral measures are put into place in order to keep product quality high:\n\n- Code review: Code changes are reviewed by a peer of the developer before it is accepted into the main code branch (for critical systems) or in a weekly post-hoc review process (for auxiliary systems). For critical systems code can only be merged if the reviewer agrees. For auxiliary systems any requested changes by reviewers are made as part of the review process. It is often necessary to add a test alongside, and the code review process ensures that this has been done as well.\n\n- Continuous integration: Before code is accepted, it is built by our continuous integration environment and tests are executed. If the build fails, the developer is notified immediately and a fix is required before the code can be merged.\n\n- Manual testing: Once the code has been merged, the change is deployed and in most cases tested manually post-release to verify quality in the production environment.\n\n- Automated integration testing: A large battery of automated tests is executed against the local and production environments and checks many common workflows for regressions of any kind. In case the tests fail, the engineer will address the issues before proceeding with attempting to merge again.\n\n- Testing of Open-Source libraries: Encore uses Open-Source libraries to provide certain functionality. Overnight tests run daily to discover potential issues, and manual testing is performed when any Open-Source libraries are version updated.\n\nAny code change is released only if all these steps succeed. Furthermore, access to the code base is protected via multi-factor authentication (MFA), which poses another layer of defense against the malicious injection of code.\n\nSince Encore depends on third-party software, we regularly contribute to the quality assurance of our suppliers. Whenever Encore becomes aware of regressions or bugs, they are reported upstream. In this way, Encore is contributing to the quality, stability, and accuracy of other software in the space.\n\n### Process monitoring\n\nWhere possible, Encore uses software to enforce processes. For example, code review and having tests passed are enforced by the source control management tool GitHub.\n\nRegular reviews on different levels (individual, team, company) foster alignment between all individuals and the company objectives.\n\n### Privacy\n\nEncore takes data privacy very seriously and complies with the rules of the European Union's GDPR (General Data Protection Regulation). GDPR grants a wide range of rights to Encore's users, such as the right to be informed, the right to access, the right to rectification, the right to erasure, and others.\n\nOne fundamental rule of the GDPR is the principle of \"data minimization\", which ensures that we are not processing more personal data than necessary. As a result, Encore Cloud uses only minimal personal data for user authentication and essential communication (a name and contact email). As described above, Encore does not store or handle passwords in any form.\n\n### Privacy policy\n\nWe are aware that confidential handling of your data is essential to establishing trust. Therefore, [Encore's Privacy Policy](https://encore.cloud/legal/privacy) ensures that the data of our users is protected according to the high standards of GDPR.\n\n## Questions and further information\n\nWe are committed to transparency in our security practices. If you have questions about our security or compliance posture, or would like to request additional documentation for your vendor review process, please contact us at [hello@encore.dev](mailto:hello@encore.dev).\n"
},
{
"path": "docs/platform/management/permissions.md",
"content": "---\nseotitle: Roles & Permissions\nseodesc: Encore helps your whole team build applications and collaborate across backend and frontend teams.\ntitle: Roles & Permissions\nsubtitle: For teams building applications together\nlang: platform\n---\n\nEncore applications have three membership roles with different permissions: **Admins**, **Members**, and **Viewers**.\nHere is a breakdown of the key differences between each role:\n\n| | Admins | Members | Viewers |\n| ----------------------------------- | ------ | ------- | ------- |\n| Manage team members | Y | N | N |\n| Connect/Disconnect cloud accounts | Y | N | N |\n| Integrate with GitHub | Y | N | N |\n| Configure custom domains | Y | N | N |\n| Manage environments | Y | N | N |\n| Create auth keys | Y | N | N |\n| Approve infrastructure provisioning | Y | N | N |\n| Delete applications | Y | N | N |\n| Push code changes | Y | Y | N |\n| Create builds & deployments | Y | Y | N |\n| Configure secrets | Y | Y | N |\n| Pull secrets | Y | Y | Y |\n| Run locally | Y | Y | Y |\n| View API documentation | Y | Y | Y |\n| View Encore Flow | Y | Y | Y |\n\n\n### Admins\n\nAdmins have full privileges and can administer your entire application.\n\n### Members\n\nMembers are active contributors to your applications. They are able to do everything that is not limited to Admins.\n \n### Viewers\n\nViewers are read-only members. They can view the Cloud Dashboard and run your application locally.\n\nThis role is intended for any team members not contributing directly to your Encore application, but who still get value from certain access. In a bigger team, this role is often appropriate for e.g. Frontend developers and Product Managers.\n\n### Custom roles & permissions\n\nCustom roles & permissions is an optional add-on to the [Pro plan](/pricing), please [contact us](mailto:hello@encore.dev) to discuss your requirements.\n"
},
{
"path": "docs/platform/management/telemetry.md",
"content": "---\nseotitle: Encore Telemetry\nseodesc: Encore collects telemetry data about app usage\ntitle: Telemetry\nlang: platform\n---\nTelemetry helps us improve the Encore by collecting usage data. This data provides insights into how Encore is used, enabling us to make informed decisions to enhance performance, add new features, and fix bugs more efficiently.\n\nEncore only collects telemetry data in the local development tools and in the Encore Cloud dashboard. It does **not** collect any telemetry data from your running applications or cloud services, ensuring complete privacy and security for your operations.\n\n## Why We Collect Data\n\nWe collect telemetry data for several important reasons:\n\n1. **Improvement of Features**: Understanding which features are most used helps us prioritize improvements and new feature development.\n2. **Performance Monitoring**: Tracking performance metrics enables us to identify and resolve issues, ensuring a smoother user experience.\n3. **Bug Detection**: Telemetry data can help us detect and fix bugs faster by providing context on how and when issues occur.\n4. **User Experience**: Insights from telemetry data guide us in making Encore more intuitive and user-friendly.\n\n## How Data is Collected\n\nEncore collects data in a way that prioritizes user privacy and security. Here's how we do it:\n\n1. **User Identifiable Data**: The data collected includes identifiable information that helps us understand specific user interactions and contexts.\n2. **Types of Data**: We collect data on usage patterns, performance metrics, and error reports.\n3. **Secure Transmission**: All data is transmitted securely using industry-standard encryption protocols.\n4. **Minimal Impact**: Data collection is designed to have minimal impact on Encore's performance.\n\n### Example of Data Being Sent\n\nHere is an example of the type of data that is sent:\n\n```json\n{\n \"event\": \"app.create\",\n \"anonymousId\": \"a-uuid-unique-for-the-installation\",\n \"properties\": {\n \"error\": false,\n \"lang\": \"go\",\n \"template\": \"graphql\"\n }\n}\n```\n\n## Data We Don't Collect\n\nAt Encore, we prioritize your privacy and ensure that no sensitive data is collected through our telemetry. Specifically, we do not collect:\n\n1. **Environment Variables**: We do not collect any environment variables set in your development or production environments.\n2. **File Paths**: The specific paths of your files and directories are not collected.\n3. **Contents of Files**: We do not access or collect the contents of your code files or any other files in your projects.\n4. **Logs**: No log files from your application or development environment are collected.\n5. **Serialized Errors**: We do not collect serialized errors that may contain sensitive information.\n\nOur goal is to gather useful data that helps improve Encore while ensuring that your sensitive information remains private and secure.\n\n## Disabling Telemetry\n\nWhile telemetry helps us improve Encore, we understand that some users may prefer to opt out. Disabling telemetry is straightforward and can be done in two ways:\n\n1. **Using the CLI Command**: You can disable telemetry by executing a simple command in your terminal.\n\n ```sh\n encore telemetry disable\n ```\n\n2. **Setting an Environment Variable**: Alternatively, you can disable telemetry by setting the `DISABLE_ENCORE_TELEMETRY` environment variable.\n\n ```sh\n export DISABLE_ENCORE_TELEMETRY=1\n ```\n\n3. **Confirmation**: After disabling telemetry, either by the CLI command or environment variable, you will receive a confirmation message indicating that telemetry has been successfully disabled.\n\n4. **Re-enabling Telemetry**: If you decide to re-enable telemetry later, you can do so with the following CLI command:\n\n ```sh\n encore telemetry enable\n ```\n\n## Debugging Telemetry\n\nFor users who want more visibility into what telemetry data is being sent, you can enable debug mode:\n\n1. **Setting Debug Mode**: Enable debug mode by setting the `ENCORE_TELEMETRY_DEBUG` environment variable.\n\n ```sh\n export ENCORE_TELEMETRY_DEBUG=1\n ```\n\n2. **Log Statements**: When debug mode is enabled, a log statement prepended by `[telemetry]` will be printed every time telemetry data is sent.\n\n## Conclusion\n\nTelemetry is a vital tool for improving Encore, but we respect your choice regarding data sharing. With easy-to-use commands and environment variables, you can manage your telemetry settings as you see fit. If you have any further questions or need assistance, please refer to our support documentation or contact our support team.\n\nThank you for helping us make Encore better!\n"
},
{
"path": "docs/platform/management/usage.md",
"content": "---\nseotitle: Usage limits and Fair Use guidelines\nseodesc: Encore comes with a built-in development cloud with generous Fair Use limits. This makes it easy to get started building your next backend application without requiring a cloud account.\ntitle: Usage limits\nsubtitle: Encore Cloud limits and Fair Use guidelines\nlang: platform\n---\n\nEncore comes with a built-in development cloud, Encore Cloud, that is free to use for development and limited scale commercial projects without any specific SLA requirements.\nEncore Cloud is subject to Fair Use guidelines and comes without warranty, as it's not intended for large-scale business-critical use cases.\n\nFor production use cases, Encore is designed to be used together with your cloud on the major cloud providers (AWS/GCP), and provides full DevOps automation for deployments to your own cloud account. This means Encore has no incentive to increase your usage – rather we can focus on building tools to help you minimize your cloud spending! (Should you wish to use Encore Cloud instead of your own cloud account, please [contact us](/book).)\n\nWhen you use Encore together with AWS/GCP, you can still use Encore Cloud to host Preview Environments and development environments.\n\n### Examples of Fair Use\n\n- Prototyping & development\n- Hobby projects\n- Commercial use cases that have limited load and do not require any SLAs\n\n### Never Fair Use\n\n- Proxies and VPNs\n- Media hosting for hot-linking\n- Scrapers\n- Crypto Mining\n- CPU-intensive APIs (e.g.: Machine Learning)\n- Load Testing\n\n## Usage guidelines\n\nWe expect most users to fall within the usage limits below.\nWe want to be as flexible and permissive as possible, and will wherever possible reach out and work with you\nto find a good solution should we notice that you are exceeding these limits.\n\nFor users on a [paid plan](/pricing), we can change these limits to support your needs. If you have significantly higher requirements,\nthis may come with an additional charge (at cost) to cover the extra capacity. Please [contact us](/book) for more information.\n\n**We will never charge you for usage of Encore Cloud unless expressly agreed in advance.**\n\n### Usage limits\n\n| | Per application |\n| ---------------- | --------------- |\n| Requests | 100,000 / day |\n| Database Storage | 1 GB |\n| PubSub Messages | 100,000 / day |\n| Cron Jobs | Once every hour |\n| Object Storage | 1 GB |\n\n### What happens if I reach a usage limit?\n\nIf your application reaches a usage limit, we will **not** automatically stop it. Our team will reach out to you, and work with you to find a solution that does not cause any undue disruption to your application."
},
{
"path": "docs/platform/migration/migrate-away.md",
"content": "---\ntitle: Migrate away from Encore\nsubtitle: If you love someone, set them free.\nlang: platform\n---\n\n_We realize most people read this page before even trying Encore, so we start with a perspective on how you might reason about adopting Encore. Read on to see what tools are available for migrating away._\n\nPicking technologies for your project is an important decision. It's tricky because you don't know what the requirements are going to look like in the future. This uncertainty makes many teams opt for maximum flexibility, often without acknowledging this has a significant negative effect on productivity.\n\nWhen designing Encore, we've leaned on standardization to provide a well-integrated and highly productive development workflow. The design is based on the core team's experience building scalable distributed systems at Spotify and Google, complemented with loads of invaluable input from the developer community. \n\nIn practise Encore is opinionated only in certain areas which are critical for enabling the static analysis used to create Encore's application model. This is fundamental to how Encore can provide its powerful features, like automatically instrumenting distributed tracing, and provisioning and managing cloud infrastructure.\n\n## Accommodating for your unique requirements\n\nMany software projects end up having a few novel requirements, which are highly specific to the problem domain. To accommodate for this, Encore is designed to let you go outside of the standardized Backend Framework when you need to, for example:\n- You can drop down in abstraction level in the API framework using [raw endpoints](/docs/ts/primitives/defining-apis#raw-endpoints)\n- You can use tools like the [Terraform provider](/docs/platform/integrations/terraform) to integrate infrastructure that is not managed by Encore\n\n## Mitigating risk through Open Source and efficiency\n\nWe believe that adopting Encore is a low-risk decision for several reasons:\n\n- There's no upfront investment needed to get the benefits\n- Encore apps are normal programs where less than 1% of the code is Encore-specific\n- All infrastructure and data is in your own cloud\n- It's simple to integrate with cloud services and systems not natively supported by Encore\n- Everything you need to develop your application is Open Source, including the [parser](https://github.com/encoredev/encore/tree/main/v2/parser), [compiler](https://github.com/encoredev/encore/tree/main/v2/compiler), [runtime](https://github.com/encoredev/encore/tree/main/runtimes)\n- Everything you need to self-host your application is [Open Source and documented](/docs/ts/self-host/build)\n\n## What to expect when migrating away\n\nIf you want to migrate away, we want to ensure this is as smooth as possible! Here are some of the ways Encore is designed to keep your app portable, with minimized lock-in, and the tools provided to aid in migrating away.\n\n### Code changes\n\nBuilding with Encore doesn't require writing your entire application in an Encore-specific way. Encore applications are normal programs where only 1% of the code is specific to Encore's Open Source Backend Framework.\n\nThis means that the changes required to stop using the Backend Framework is almost exactly the same work you would have needed to do if you hadn't used Encore in the first place, e.g. writing infrastructure boilerplate. There is no added migration cost.\n\n### Deployment\n\nIf you are self-hosting your application, then you're already done.\n\nIf you are using Encore Cloud to manage deployments and want to migrate to your own solution, you can use the `encore build docker` command to produce a Docker image, containing the compiled application, using exactly the same code path as Encore's CI system to ensure compatibility.\n\nLearn more in the [self-hosting docs](/docs/ts/self-host/build).\n\n### Tell us what you need\n\nWe're engineers ourselves and we understand the importance of not being constrained by a single technology.\n\nWe're working every single day on making it even easier to start, and stop, using Encore.\nIf you have specific concerns, questions, or requirements, we'd love to hear from you!\n\nPlease reach out on [Discord](https://encore.dev/discord) or [send an email](mailto:hello@encore.dev) with your thoughts.\n"
},
{
"path": "docs/platform/migration/migrate-to-encore.md",
"content": "---\ntitle: Migrating an existing system to Encore\nsubtitle: Approaches for adopting Encore\nseotitle: How to migrate your existing system to Encore\nseodesc: Learn how to migrate your application to Encore incrementally, and unlock Encore's powerful set of development tools for your team.\nlang: platform\n---\n\nBy building your application with the Encore open-source framework, you unlock powerful features such as the [local development tools](/docs/ts/observability/dev-dash), [automatic infrastructure provisioning](/docs/platform/infrastructure/infra), [distributed tracing](/docs/ts/observability/tracing), and [service catalog](/docs/ts/observability/service-catalog).\n\n**The good news: you don't need a complete rewrite.** This guide shows you how to adopt Encore incrementally, so you can start benefiting immediately while gradually migrating your existing system.\n\n## Why incremental migration?\n\nIncremental migration is more reliable than a complete rewrite. Here's why:\n\n- **Immediate value** - Start benefiting from Encore's features when developing your next new service.\n- **Lower risk** - Small, controlled changes instead of a single high-stakes big-bang launch.\n- **Ship faster** - Deliver improvements incrementally rather than waiting for a complete rewrite.\n\n## Choose your migration strategy\n\nWe recommend two approaches:\n\n1. **Service by service** (Recommended) - Migrate services one at a time. Run Encore alongside your legacy system, integrated via APIs.\n2. **Forklift migration** - Move your entire application in one shot using a catch-all handler, then refactor incrementally.\n\n![](\"/assets/docs/migration-diagram.png\" "\\"Migration")
\n\n### Need help?\n\nWe've helped 100+ teams adopt Encore and we're happy to answer your questions and provide advice to help you with your migration.\n\n[Email us](mailto:hello@encore.dev) to ask questions, or [book a 1:1 call](https://encore.dev/book) to discuss your specific situation.\n\n**Enterprise customers**: Encore Cloud can adapt to your unique infrastructure—Kubernetes clusters, VPCs, security policies, and compliance needs—typically within days. [Contact us](https://encore.dev/book) to discuss your requirements.\n\n## Service by service migration (Recommended)\n\nMigrate services one at a time while your Encore application runs alongside your legacy system, integrated through APIs.\n\n### Key benefits\n\n- **Full Encore features immediately** - Get automatic infrastructure provisioning, distributed tracing, and architecture diagrams for each migrated service.\n- **Independent services** - Each service is self-contained with no cross-application dependencies.\n- **Simple integration** - Services communicate via APIs.\n- **Flexible deployment** - Deploy to your existing Kubernetes cluster, or let Encore Cloud set up a new project in your cloud (AWS/GCP).\n- **Better developer experience** - Start building with modern tooling right away.\n\n### Deployment options\n\nChoose how to deploy your Encore application:\n\n- **Your Kubernetes cluster** - Deploy directly to your existing Kubernetes infrastructure. Run Encore alongside legacy systems securely in the same environment.\n- **Encore-managed in your cloud account** - Let Encore handle all infrastructure provisioning and management in your AWS or GCP account, and deploy within your existing VPC and security setup.\n\n**Enterprise**: We can adapt to your specific network topology, security policies, and compliance requirements — typically within days. [Contact us](https://encore.dev/book) to discuss your requirements.\n\n_Google Cloud example architecture:_\n\n![](\"/assets/docs/grafanastack.png\" "\\"Add")
\n\nNext, open the environment **Overview** for the environment you wish to sent metrics from and click on **Settings**.\nThen in the **Sending metrics data** section, select your Grafana Cloud Stack from the drop-down and save.\n\n![](\"/assets/docs/configstack.png\" "\\"Select")
\n\nThat's it! After your next deploy, Encore will start sending metrics data to your Grafana Cloud Stack.\n\n![](\"/assets/docs/datadogaccount.png\" "\\"Add")
\n\nNext, open the environment **Overview** for the environment you wish to sent metrics from and click on **Settings**.\nThen in the **Sending metrics data** section, select your Datadog Account from the drop-down and save.\n\n![](\"/assets/icons/features/higher.png\"){kind=icon}
\n ![](\"/assets/icons/features/meet.png\"){kind=icon}
\n ![](\"https://encore.dev/assets/blog/worker-pooling/encore-pooling.png\")
\n\n## Enabling Worker Pooling\n\nTo enable Worker Pooling, add `\"build\": {\"worker_pooling\": true}` to your `encore.app` file.\n\n## Designing your application to work with Worker Pooling\n\nMost application code will work with Worker Pooling without any changes. However, it's important to understand\nthe implications of running in a multi-threaded environment.\n\nWhen utilizing Worker Pooling, Encore.ts will automatically spin up multiple NodeJS isolates (one per CPU) to handle incoming requests.\nEach NodeJS isolate is a separate JavaScript runtime, with its own event loop and memory space.\n\nThis means that you cannot rely on global shared state that is shared across all incoming requests,\nsince each request may be handled by a different NodeJS isolate.\n"
},
{
"path": "docs/ts/develop/orms/drizzle.md",
"content": "---\nseotitle: Using Drizzle with Encore\nseodesc: Learn how to use Drizzle with Encore to interact with SQL databases.\ntitle: Using Drizzle ORM with Encore\nlang: ts\n---\nEncore.ts supports integrating [Drizzle](https://orm.drizzle.team/), a TypeScript ORM for Node.js and the browser. To use Drizzle with Encore, start by creating a `SQLDatabase` instance and providing the connection string to Drizzle.\n \n\n {\n mutation.mutate({\n id: Date.now(),\n title: 'Do Laundry',\n })\n }}\n >\n Add Todo\n \n
\n )\n}\n\nrender(- \n {query.data?.map((todo) => (\n
- {todo.title} \n ))}\n
Person Page
\nName: <%= name %>
\n```\n\n## Serving from a dynamic path\n\nThis example is similar to the one above, but in this case we use a fallback path to serve a template file based on the path. We use the `currentRequest` function to get the `path` and then render the template file based on the `path`. If no path is provided, we default to `index.html`.\n\n```ts\nimport { api } from \"encore.dev/api\";\nimport { APICallMeta, currentRequest } from \"encore.dev\";\nimport ejs, { Options } from \"ejs\";\n\nconst BASE_PATH = \"./template/views\";\nconst ejsOptions: Options = { views: [BASE_PATH] };\n\nexport const servePathTemplate = api.raw(\n { expose: true, path: \"/!path\", method: \"GET\" },\n async (req, resp) => {\n const { path } = (currentRequest() as APICallMeta).pathParams;\n const viewPath = `${BASE_PATH}/${path ?? \"index\"}.html`;\n const html = await ejs.renderFile(viewPath, ejsOptions);\n resp.setHeader(\"content-type\", \"text/html\");\n resp.end(html);\n },\n);\n```\n\n## Serving inline HTML\n\nIn this example we are serving inline HTML with EJS. We use the `ejs.render` function to render the inline HTML with the given data.\n\n```ts\nimport { api } from \"encore.dev/api\";\nimport ejs, { Options } from \"ejs\";\n\nconst inlineHTML = `\n\n\n \n \n \n \n \nStatic Inline HTML Example
\nName: <%= name %>!
\n \n\n`;\n\nexport const serveInlineHTML = api.raw(\n { expose: true, path: \"/html\", method: \"GET\" },\n async (req, resp) => {\n const html = ejs.render(inlineHTML, { name: \"Simon\" });\n resp.setHeader(\"Content-Type\", \"text/html\");\n resp.end(html);\n },\n);\n```\n\n## Static files\n\nIn the above example we are fetching a stylesheet from the `/public` path. We can use the `api.static` function to serve all files in the `./assets` directory under the `/public` path prefix:\n\n```ts\n// Serve all files in the ./assets directory under the /public path prefix.\nexport const assets = api.static({\n expose: true,\n path: \"/public/*path\",\n dir: \"./assets\",\n});\n```\n\nLearn more about serving static files in the [Static Files](/docs/ts/primitives/static-assets) guide.\n" }, { "path": "docs/ts/how-to/file-uploads.md", "content": "---\nseotitle: How to handle file uploads in you Encore.ts application\nseodesc: Learn how to store file uploads as bytes in a database and serving them back to the client.\ntitle: Handling file uploads\nlang: ts\n---\n\nIn this guide you will learn how to handle file uploads from a client in your Encore.ts backend.\n\n\n