**Existing projects:** Run `encore llm-rules init` to add AI support:
```bash
encore llm-rules init
```
This prompts you to select a tool and generates the appropriate configuration file (`.cursorrules`, `CLAUDE.md`, etc.).
Both 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.
Supported tools: Cursor, Claude Code, VS Code, AGENTS.md, and Zed.
### Method 2: Using Encore Skills
Use the [Encore skills package](https://github.com/encoredev/skills) which works with Cursor, Claude Code, GitHub Copilot, and 10+ other AI agents:
```bash
npx add-skill encoredev/skills
```
You can also install specific skills or target specific agents:
```bash
# List available skills
npx add-skill encoredev/skills --list
# Install to specific agents
npx add-skill encoredev/skills -a cursor -a claude-code
```
The 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.
## MCP Server
Encore'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.
### Start the Server
From your Encore app directory:
```bash
encore mcp start
```
This displays connection information. Keep it running while using your AI tools.
### Connect Cursor
**Quick setup:** Use this button (update `your-app-id` to your actual app ID):
## Standardization brings clarity
Developers 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.
When 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.
================================================
FILE: docs/go/concepts/benefits.md
================================================
---
seotitle: Benefits of using Encore.go
seodesc: See how Encore.go helps you build backends faster using Go.
title: Encore.go Benefits
subtitle: How Encore.go helps you build robust distributed systems, faster.
lang: go
---
Using Encore.go to declare infrastructure in application code helps unlock several benefits:
- **Local development with instant infrastructure**: Encore.go automatically sets up necessary infrastructure as you develop.
- **Rapid feedback**: Catch issues early with type-safe infrastructure, avoiding slow deployment cycles.
- **No manual configuration required**: No need for Infrastructure-as-Code. Your code is the single source of truth.
- **Unified codebase**: One codebase for all environments; local, preview, and cloud.
- **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.
- **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.
- **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.
## No DevOps experience required
Encore provides open source tools to help you integrate with your cloud infrastructure, enabling you to self-host your application anywhere that supports Docker containers.
Learn more in the [self-host documentation](/docs/go/self-host/docker-build).
You 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.
This 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.
## Simplicity without giving up flexibility
Encore.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.
================================================
FILE: docs/go/develop/api-docs.md
================================================
---
seotitle: Service Catalog & Generated API Docs
seodesc: See how Encore automatically generates API documentation that always stays up to date and in sync.
title: Service Catalog
subtitle: Automatically get a Service Catalog and complete API docs
---
All developers agree API documentation is great to have, but the effort of maintaining it inevitably leads to docs becoming stale and out of date.
To 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.
The 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).
================================================
FILE: docs/go/develop/auth.md
================================================
---
seotitle: Adding authentication to APIs to auth users
seodesc: Learn how to add authentication to your APIs and make sure you know who's calling your backend APIs.
title: Authenticating users
subtitle: Knowing what's what and who's who
infobox: {
title: "Authentication",
import: "encore.dev/beta/auth",
}
lang: go
---
Almost every application needs to know who's calling it, whether the user
represents a person in a consumer-facing app or an organization in a B2B app.
Encore supports both use cases in a simple yet powerful way.
As described in the docs for [defining APIs](/docs/go/primitives/defining-apis), Encore offers three access levels
for APIs:
* `//encore:api public` – defines a public API that anybody on the internet can call.
* `//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.
* `//encore:api auth` – defines a public API that anybody can call, but that requires valid authentication.
When an API is defined with access level `auth`, outside calls to that API must specify
an authorization header, in the form `Authorization: Bearer 
## Integration testing
Since Encore removes almost all boilerplate, most of the code you write
is business logic that involves databases and calling APIs between services.
Such behavior is most easily tested with integration tests.
When running tests, Encore automatically sets up the databases you need
in a separate database cluster. They are additionally configured to skip `fsync`
and to use an in-memory filesystem since durability is not a concern for automated tests.
This drastically reduces the speed overhead of writing integration tests.
In general, Encore applications tend to focus more on integration tests
compared to traditional applications that are heavier on unit tests.
This is nothing to worry about and is the recommended best practice.
### Temporary databases
When Encore runs tests, by default it reuses the same database for all tests,
to improve performance. However, this means that you need to take care when writing tests
to ensure tests don't interfere with each other.
If you instead want to have a separate database for a given test, you can use
[`et.NewTestDatabase`](https://pkg.go.dev/encore.dev/et#NewTestDatabase) to create a temporary database
that only exists for the duration of the test.
The temporary test database is a fully-migrated database. It does not include any data written by other tests.
Next, go to the *Application Settings* section. There you will find the `Domain`, `Client ID`, and `Client Secret` that you need to communicate with Auth0.
Copy these values, we will need them shortly.
A callback URL is where Auth0 redirects the user after they have been authenticated.
Add `http://localhost:3000/callback` to the *Allowed Callback URLs*.
You will need to add more URLs to this list when you have a production or staging environments.
The same goes for the logout URL (were the user will get redirected after logout). Add `http://localhost:3000/` to the *Allowed Logout URLs*.
## Config and secrets
Create a [configuration file](/docs/go/develop/config) in the `auth` service and name it `auth-config.cue`. Add the following:
```cue
ClientID: "
As well as the [Flow architecture diagram](/docs/go/observability/encore-flow).
## Sharing databases between services (or not)
Deciding 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).
================================================
FILE: docs/go/how-to/cgo.md
================================================
---
seotitle: Build Go applications with cgo using Encore
seodesc: Learn how to build Go applications with cgo using Encore
title: Build with cgo
lang: go
---
Cgo is a feature of the Go compiler that enables Go programs to interface
with libraries written in other languages using C bindings.
By default, for improved portability Encore builds applications with cgo support disabled.
To enable cgo for your application, add `"build": {"cgo_enabled": true}` to your `encore.app` file.
For example:
```json
-- encore.app --
{
"id": "my-app-id",
"build": {
"cgo_enabled": true
}
}
```
With this setting Encore's build system will compile the application using an Ubuntu builder image
with gcc pre-installed.
## Static linking
To keep the resulting Docker images as minimal as possible, Encore compiles applications with static linking.
This happens even with cgo enabled. As a result the cgo libraries you use must support static linking.
In some cases, you may need to add additional linker flags to properly work with static linking of cgo libraries.
See the [official cgo docs](https://pkg.go.dev/cmd/cgo) for more information on how to do this.
================================================
FILE: docs/go/how-to/clerk-auth.md
================================================
---
seotitle: How to use Clerk to authenticate users in your backend application
seodesc: 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.
title: Use Clerk with your app
lang: go
---
In this guide you will learn how to set up an Encore [auth handler](/docs/go/develop/auth#the-auth-handler) that makes use of
[Clerk](https://clerk.com/) in order to add an integrated signup and login experience to your web app.
For 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.
## Set up the auth handler
In your Encore app, install the following module:
```shell
$ go get github.com/clerkinc/clerk-sdk-go/clerk
```
Create a folder and naming it `auth`, this is where our authentication related backend code will live.
It's time to define your [auth handler](/docs/go/develop/auth). Create `auth/auth.go` and paste the following:
```go
package auth
import (
"context"
"encore.dev/beta/auth"
"encore.dev/beta/errs"
"github.com/clerkinc/clerk-sdk-go/clerk"
)
var secrets struct {
ClientSecretKey string
}
// Service struct definition.
// Learn more: encore.dev/docs/primitives/services-and-apis/service-structs
//
//encore:service
type Service struct {
client clerk.Client
}
// initService is automatically called by Encore when the service starts up.
func initService() (*Service, error) {
client, err := clerk.NewClient(secrets.ClientSecretKey)
if err != nil {
return nil, err
}
return &Service{client: client}, nil
}
type UserData struct {
ID string `json:"id"`
Username *string `json:"username"`
FirstName *string `json:"first_name"`
LastName *string `json:"last_name"`
ProfileImageURL string `json:"profile_image_url"`
PrimaryEmailAddressID *string `json:"primary_email_address_id"`
EmailAddresses []clerk.EmailAddress `json:"email_addresses"`
}
// The `encore:authhandler` annotation tells Encore to run this function for all
// incoming API call that requires authentication.
// Learn more: encore.dev/docs/develop/auth#the-auth-handler
//
//encore:authhandler
func (s *Service) AuthHandler(ctx context.Context, token string) (auth.UID, *UserData, error) {
// verify the session
sessClaims, err := s.client.VerifyToken(token)
if err != nil {
return "", nil, &errs.Error{
Code: errs.Unauthenticated,
Message: "invalid token",
}
}
user, err := s.client.Users().Read(sessClaims.Claims.Subject)
if err != nil {
return "", nil, &errs.Error{
Code: errs.Internal,
Message: err.Error(),
}
}
userData := &UserData{
ID: user.ID,
Username: user.Username,
FirstName: user.FirstName,
LastName: user.LastName,
ProfileImageURL: user.ProfileImageURL,
PrimaryEmailAddressID: user.PrimaryEmailAddressID,
EmailAddresses: user.EmailAddresses,
}
return auth.UID(user.ID), userData, nil
}
```
## Clerk credentials
Create a Clerk account if you haven't already. Then, in the Clerk dashboard, create a new applications.
Next, go to the *API Keys* page for your app. Copy one of the "Secret keys" (the "Publishable Key" will be used by your frontend).
The `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).
From your terminal (inside your Encore app directory), run:
```shell
$ encore secret set --prod ClientSecretKey
```
Now 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).
Once you have a client secret for development, set it similarly to before:
```shell
$ encore secret set --dev ClientSecretKey
```
## Frontend
Clerk offers a [React SDK](https://clerk.com/docs/references/react/overview) for the frontend which makes it really simple to integrate
a login/signup flow inside your web app as well as getting the token required to communicate with your Encore backend.
You can use the `useAuth` hook from `@clerk/clerk-react` to get the token and send it to your backend.
```tsx
import { useAuth } from '@clerk/clerk-react';
export default function ExternalDataPage() {
const { getToken, isLoaded, isSignedIn } = useAuth();
if (!isLoaded) {
// Handle loading state however you like
return 
3. Create an application for your frontend application
- Go to "Applications" in Logto Console
- 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)
- (Optional, we'll cover this later) Integrate Logto with your frontend application according to the guide in the Logto Console.
- Note down the application ID and issuer URL on the Application details page as we'll need them later
## Setup the auth handler
Now 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.
Add these two modules in your Encore application:
```shell
$ go get github.com/golang-jwt/jwt/v5
$ go get github.com/MicahParks/keyfunc/v3
```
Create `auth/auth.go` and add the following code:
```go
package auth
import (
"context"
"time"
"encore.dev/beta/auth"
"encore.dev/beta/errs"
"encore.dev/config"
"github.com/MicahParks/keyfunc/v3"
"github.com/golang-jwt/jwt/v5"
)
// Configuration variables for authentication
type LogtoAuthConfig struct {
// The issuer URL
Issuer config.String
// URL to fetch JSON Web Key Set (JWKS)
JwksUri config.String
// Expected audience for the JWT
ApiResourceIndicator config.String
// Expected client ID in the token claims
ClientId config.String
}
var authConfig *LogtoAuthConfig = config.Load[*LogtoAuthConfig]()
// RequiredClaims defines the expected structure of JWT claims
// Extends the standard JWT claims with a custom ClientID field
type RequiredClaims struct {
ClientID string `json:"client_id"`
jwt.RegisteredClaims
}
// AuthHandler validates JWT tokens and extracts the user ID
// Implements Encore's authentication handler interface
//
//encore:authhandler
func AuthHandler(ctx context.Context, token string) (auth.UID, error) {
// Fetch and parse the JWKS (JSON Web Key Set) from the identity provider
jwks, err := keyfunc.NewDefaultCtx(ctx, []string{authConfig.JwksUri()})
if err != nil {
return "", &errs.Error{
Code: errs.Internal,
Message: "failed to fetch JWKS",
}
}
// Parse and validate the JWT token with required claims and validation options
parsedToken, err := jwt.ParseWithClaims(
token,
&RequiredClaims{},
jwks.Keyfunc,
// Expect the token to be intended for this API resource
jwt.WithAudience(authConfig.ApiResourceIndicator()),
// Expect the token to be issued by this issuer
jwt.WithIssuer(authConfig.Issuer()),
// Allow some leeway for clock skew
jwt.WithLeeway(time.Minute*10),
)
// Check if there were any errors during token parsing
if err != nil {
return "", &errs.Error{
Code: errs.Unauthenticated,
Message: "invalid token",
}
}
// Verify that the client ID in the token matches the expected client ID
if parsedToken.Claims.(*RequiredClaims).ClientID != authConfig.ClientId() {
return "", &errs.Error{
Code: errs.Unauthenticated,
Message: "invalid token",
}
}
// Extract the user ID (subject) from the token claims
userId, err := parsedToken.Claims.GetSubject()
if err != nil {
return "", &errs.Error{
Code: errs.Unauthenticated,
Message: "invalid token",
}
}
// Return the user ID as an Encore auth.UID
return auth.UID(userId), nil
}
```
Create a [configuration file](https://encore.dev/docs/go/develop/config) in the auth service and name it `auth-config.cue`. Add the following:
```cue
Issuer: "
## Real-time updates
Flow 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.
When developing locally, Flow will auto update in real-time to reflect your architecture as you
make code changes. This helps you be mindful of important dependencies and makes it clear if you introduce new ones.
For cloud environments, Flow auto-updates with each deploy.
In the example below a new subscription on the topic `payment-made` is introduced and then removed in `user` service:
================================================
FILE: docs/go/observability/logging.md
================================================
---
seotitle: Use structured logging to understand your application
seodesc: 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.
title: Logging
subtitle: Structured logging helps you understand your application
lang: go
infobox: {
title: "Structured Logging",
import: "encore.dev/rlog",
}
---
Encore 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.
Encore’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.
## Usage
First, import `encore.dev/rlog` in your package. Then simply call one of the package methods `Info`, `Error`, or `Debug`. For example:
```go
rlog.Info("log message",
"user_id", 12345,
"is_subscriber", true)
rlog.Error("something went terribly wrong!",
"err", err)
```
The first parameter is the log message. After that follows zero or more key-value pairs for structured logging for context.
If 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:
```go
ctx := rlog.With("is_subscriber", true)
ctx.Info("user logged in", "login_method", "oauth") // includes is_subscriber=true
```
For more information, see the [API Documentation](https://pkg.go.dev/encore.dev/rlog).
## Live-streaming logs
Encore also makes it simple to live-stream logs directly to your terminal, from any environment, by running:
```
$ encore logs --env=prod
```
================================================
FILE: docs/go/observability/metrics.md
================================================
---
seotitle: Custom metrics in Go
seodesc: Learn how to define and use custom metrics in your Go backend application with Encore.
title: Metrics
subtitle: Track custom metrics in your Go application
infobox: {
title: "Metrics",
import: "encore.dev/metrics",
}
lang: go
---
Encore 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.
See the [Platform metrics documentation](/docs/platform/observability/metrics) for information about integrations with third-party services like Grafana Cloud and Datadog.
## Defining custom metrics
Define custom metrics by importing the [`encore.dev/metrics`](https://pkg.go.dev/encore.dev/metrics) package and
creating a new metric using one of the `metrics.NewCounter` or `metrics.NewGauge` functions.
For example, to count the number of orders processed:
```go
import "encore.dev/metrics"
var OrdersProcessed = metrics.NewCounter[uint64]("orders_processed", metrics.CounterConfig{})
func process(order *Order) {
// ...
OrdersProcessed.Increment()
}
```
## Metric types
Encore currently supports two metric types: counters and gauges.
**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.
**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.
For 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).
### Counter example
```go
import "encore.dev/metrics"
var RequestsReceived = metrics.NewCounter[uint64]("requests_received", metrics.CounterConfig{})
func handleRequest() {
RequestsReceived.Increment()
// ... handle request
}
```
### Gauge example
```go
import "encore.dev/metrics"
var ActiveConnections = metrics.NewGauge[int64]("active_connections", metrics.GaugeConfig{})
func onConnect() {
ActiveConnections.Add(1)
}
func onDisconnect() {
ActiveConnections.Add(-1)
}
```
## Defining labels
Encore'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`.
The 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`.
### Counter with labels
```go
import "encore.dev/metrics"
type Labels struct {
Success bool
}
var OrdersProcessed = metrics.NewCounterGroup[Labels, uint64]("orders_processed", metrics.CounterConfig{})
func process(order *Order) {
var success bool
// ... populate success with true/false ...
OrdersProcessed.With(Labels{Success: success}).Increment()
}
```
### Gauge with labels
```go
import "encore.dev/metrics"
type ConnectionLabels struct {
Region string
}
var ActiveConnections = metrics.NewGaugeGroup[ConnectionLabels, int64]("active_connections", metrics.GaugeConfig{})
func onConnect(region string) {
ActiveConnections.With(ConnectionLabels{Region: region}).Add(1)
}
```
### Using the CLI
If you prefer, you can also set up secrets from the CLI using:
## How it works: Where secrets are stored
When you store a secret Encore stores it encrypted using Google Cloud Platform's [Key Management Service](https://cloud.google.com/security-key-management) (KMS).
- **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.
- **Local:** For local secrets Encore automatically replicates them to developers' machines when running `encore run`.
- **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.
### Overriding local secrets
When setting secrets via the `encore secret set` command, they are automatically synced to all developers
working on the same application, courtesy of Encore Cloud.
In some cases, however, you want to override a secret only for your local machine.
This can be done by creating a file named `.secrets.local.cue` in the root of your Encore application,
next to the `encore.app` file.
The file contains key-value pairs of secret names to secret values. For example:
```cue
GitHubAPIToken: "my-local-override-token"
SSHPrivateKey: "custom-ssh-private-key"
```
================================================
FILE: docs/go/primitives/service-structs.md
================================================
---
seotitle: Service Structs
seodesc: Learn how to use service structs to define APIs as methods.
title: Service structs
lang: go
---
Encore 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).
You 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.
It works by defining a struct type of your choice (typically called `Service`)
and declaring it with `//encore:service`.
Then, you can define a special function named `initService`
(or `initWhatever` if you named the type `Whatever`)
that gets called by Encore to initialize your service when it starts up.
It looks like this:
```go
//encore:service
type Service struct {
// Add your dependencies here
}
func initService() (*Service, error) {
// Write your service initialization code here.
}
//encore:api public
func (s *Service) MyAPI(ctx context.Context) error {
// ...
}
```
You can also open a separate terminal to call your API endpoint:
```shell
$ curl http://localhost:4000/hello/world
{"Message": "Hello, world!"}
```
If you see this JSON response, you've successfully made an API call to your very first Encore application. Well done, you're on your way!
### Review a trace of the request
You can now take a look at the trace for the request you just made by clicking on it in the right column in the local dashboard.
With such a simple API, there's not much to it, just a simple request and response.
However, just imagine how powerful it is to have tracing when you're developing a more complex system with multiple services, Pub/Sub, and databases.
(Learn more about Encore's tracing capabilities in the [tracing docs](/docs/go/observability/tracing).)
## 4. Make a code change
Let's put our mark on this API and make our first code change.
🥐 Head back to your code editor and look at the `hello.go` file again.
If you can't come up a creative change yourself, why not simply change the "Hello" message to a more sassy "Howdy"?
🥐 Once you've made your change, save the file.
When you save, the daemon run by the Encore CLI instantly detects the change and automatically recompiles your application and reloads your local development environment.
The output where you're running your app will look something like this:
```output
Changes detected, recompiling...
Reloaded successfully.
TRC registered endpoint endpoint=World path=/hello/:name service=hello
TRC listening for incoming HTTP requests
```
🥐 Test your change by calling your API again.
```shell
$ curl http://localhost:4000/hello/world
{"Message": "Howdy, world!"}
```
Great job, you made a change and your app was reloaded automatically.
Now you're ready to head to the cloud!
## 5. Deploy your app
### Generating Docker image
You can either deploy by generating a Docker image for you app using:
```shell
$ encore build docker MY-IMAGE:TAG
```
This will compile your application using the host machine and then produce a Docker image containing the compiled application.
You can now deploy this anywhere you like. Learn more in the [self-host docs](/docs/go/self-host/docker-build).
### Deploy using Encore Cloud
Optionally, you can use [Encore Cloud](https://encore.dev/use-cases/devops-automation) to automatically deploy your application.
It comes with built-in free development hosting, and for production offers fully automated deployment to your own cloud on AWS or GCP.
🥐 To deploy, simply push your changes to Encore:
```shell
$ git add -A .
$ git commit -m 'Initial commit'
$ git push encore
```
Encore Cloud will now build and test your app, provision the needed infrastructure, and deploy your application to a staging environment.
After triggering the deployment, you will see a URL where you can view its progress in the Encore Cloud dashboard.
It will look something like: `https://app.encore.cloud/$APP_ID/deploys/...`
🥐 Open the URL to access the Encore Cloud dashboard and check the progress of your deployment.
You can now use the Cloud Dashboard to view production [traces](/docs/go/observability/tracing), [connect your cloud account](/docs/platform/deploy/own-cloud), [integrate with GitHub](/docs/platform/integrations/github), and much more.
## What's next?
- Check out the [REST API tutorial](/docs/go/tutorials/rest-api) to learn how to create endpoints, use databases, and more.
- Join the friendly community on [Discord](/discord) to ask questions and meet other Encore developers.
================================================
FILE: docs/go/self-host/ci-cd.md
================================================
---
seotitle: Integrate with your CI/CD pipeline
seodesc: Learn how to integrate Encore.go with your CI/CD pipeline.
title: Integrate with your CI/CD pipeline
lang: go
---
Encore seamlessly integrates with any CI/CD pipeline through its CLI tools. You can automate Docker image creation using the `encore build` command as part of your deployment workflow.
## Integrating with CI/CD Platforms
While every CI/CD pipeline is unique, integrating Encore follows a straightforward process. Here are the key steps:
1. Install the Encore CLI in your CI environment
2. Use `encore build docker` to create Docker images
3. Push the images to your container registry
4. Deploy to your infrastructure
If your app is linked with Encore Cloud, you'll need to authenticate the CLI in your CI environment using an [auth key](/docs/platform/integrations/auth-keys). Generate one from **App Settings > Auth Keys** in the Encore Cloud dashboard, store it as a CI secret, and run `encore auth login --auth-key=
If 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)
## 1. Create your Encore application
## 2. Create booking service
Let's start by creating the functionality to view bookable slots.
With 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.
We already have a Go package named `booking`, let's turn that into an Encore service.
🥐 Inside the `booking` folder, create a file named `slots.go`.
```shell
$ touch booking/slots.go
```
🥐 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).
```go
-- booking/slots.go --
// Service booking keeps track of bookable slots in the calendar.
package booking
import (
"context"
"github.com/jackc/pgx/v5/pgtype"
"time"
)
const DefaultBookingDuration = 1 * time.Hour
type BookableSlot struct {
Start time.Time `json:"start"`
End time.Time `json:"end"`
}
type SlotsParams struct{}
type SlotsResponse struct{ Slots []BookableSlot }
//encore:api public method=GET path=/slots/:from
func GetBookableSlots(ctx context.Context, from string) (*SlotsResponse, error) {
fromDate, err := time.Parse("2006-01-02", from)
if err != nil {
return nil, err
}
const numDays = 7
var slots []BookableSlot
for i := 0; i < numDays; i++ {
date := fromDate.AddDate(0, 0, i)
daySlots, err := bookableSlotsForDay(date)
if err != nil {
return nil, err
}
slots = append(slots, daySlots...)
}
return &SlotsResponse{Slots: slots}, nil
}
func bookableSlotsForDay(date time.Time) ([]BookableSlot, error) {
// 09:00
availStartTime := pgtype.Time{
Valid: true,
Microseconds: int64(9*3600) * 1e6,
}
// 17:00
availEndTime := pgtype.Time{
Valid: true,
Microseconds: int64(17*3600) * 1e6,
}
availStart := date.Add(time.Duration(availStartTime.Microseconds) * time.Microsecond)
availEnd := date.Add(time.Duration(availEndTime.Microseconds) * time.Microsecond)
// Compute the bookable slots in this day, based on availability.
var slots []BookableSlot
start := availStart
for {
end := start.Add(DefaultBookingDuration)
if end.After(availEnd) {
break
}
slots = append(slots, BookableSlot{
Start: start,
End: end,
})
start = end
}
return slots, nil
}
```
The 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.
We are also returning time slots that have already passed. Don't worry, we'll come back and fix it later on.
🥐 Let's try it! Open up the Local Development Dashboard running at [http://localhost:9400](http://localhost:9400) and try calling
the `booking.GetBookableSlots` endpoint, passing in `2024-12-01`.
If you prefer to use the terminal instead run `curl http://localhost:4000/slots/2024-12-01` in
a new terminal instead. Either way you should see the response:
```json
{
"Slots": [
{
"start": "2024-12-01T09:00:00Z",
"end": "2024-12-01T10:00:00Z"
},
{
"start": "2024-12-01T10:00:00Z",
"end": "2024-12-01T11:00:00Z"
},
{
"start": "2024-12-01T11:00:00Z",
"end": "2024-12-01T12:00:00Z"
},
...
]
}
```
## 3. Book an appointment
Next, 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.
🥐 Let's create a SQL database for our booking service and the required sqlc scaffolding. Create the following file structure:
```
/my-app
└── booking // booking service (a Go package)
├── db // (New) db related files (directory)
│ ├── migrations // (New) db migrations (directory)
│ │ └── 1_create_tables.up.sql // (New) db migration schema
│ └── query.sql // (New) SQL queries
├── sqlc.yaml // (New) sqlc config file
├── slots.go // booking service code
└── helpers.go // booking service code
```
🥐 Naming of the database migration file is important, it must look something like: `1_
🥐 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.
```shell
$ encore secret set --type dev,local,pr SlackWebhookURL
$ encore secret set --type prod SlackWebhookURL
```
🥐 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`:
```go
// Service slack calls a webhook to post notifications to Slack.
package slack
import (
"bytes"
"context"
"encoding/json"
"encore.dev/beta/errs"
"io"
"net/http"
)
type NotifyParams struct {
Text string `json:"text"`
}
//encore:api private
func Notify(ctx context.Context, p *NotifyParams) error {
eb := errs.B()
reqBody, err := json.Marshal(p)
if err != nil {
return err
}
req, err := http.NewRequestWithContext(ctx, "POST", secrets.SlackWebhookURL, bytes.NewReader(reqBody))
if err != nil {
return err
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
if resp.StatusCode >= 400 {
body, _ := io.ReadAll(resp.Body)
return eb.Code(errs.Unavailable).Msgf("notify slack: %s: %s", resp.Status, body).Err()
}
return nil
}
var secrets struct {
SlackWebhookURL string
}
```
🥐 Now let's call the API again from the local development dashboard, or from the terminal:
```shell
$ curl http://localhost:4000/url -d '{"URL": "https://encore.dev"}'
```
🥐 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;`:
```shell
$ encore db shell url
psql (13.1, server 11.12)
Type "help" for help.
url=# select * from url;
id | original_url
----------+--------------------
zr6RmZc4 | https://encore.dev
(1 row)
```
That was easy!
## 3. Add endpoint to retrieve URLs
To complete our URL shortener API, let’s add the endpoint to retrieve a URL given its short id.
🥐 Add this endpoint to `url/url.go`:
```go
-- url/url.go --
// Get retrieves the original URL for the id.
//encore:api public method=GET path=/url/:id
func Get(ctx context.Context, id string) (*URL, error) {
u := &URL{ID: id}
err := db.QueryRow(ctx, `
SELECT original_url FROM url
WHERE id = $1
`, id).Scan(&u.URL)
return u, err
}
```
Encore 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.
🥐 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:
You can also call it directly from the terminal:
```shell
$ curl http://localhost:4000/url/zr6RmZc4
```
You should now see this:
```json
{
"ID": "zr6RmZc4",
"URL": "https://encore.dev"
}
```
It works! That's how you build REST APIs and use PostgreSQL databases in Encore.
## 4. Add a test
Before deployment, it is good practice to have tests to assure that
the service works properly. Such tests including database access
are easy to write.
We've prepared a test to check that the whole cycle of shortening
the URL, storing and then retrieving the original URL works.
🥐 Save this in a separate file `url/url_test.go`.
```go
-- url/url_test.go --
package url
import (
"context"
"testing"
)
// TestShortenAndRetrieve - test that the shortened URL is stored and retrieved from database.
func TestShortenAndRetrieve(t *testing.T) {
testURL := "https://github.com/encoredev/encore"
sp := ShortenParams{URL: testURL}
resp, err := Shorten(context.Background(), &sp)
if err != nil {
t.Fatal(err)
}
wantURL := testURL
if resp.URL != wantURL {
t.Errorf("got %q, want %q", resp.URL, wantURL)
}
firstURL := resp
gotURL, err := Get(context.Background(), firstURL.ID)
if err != nil {
t.Fatal(err)
}
if *gotURL != *firstURL {
t.Errorf("got %v, want %v", *gotURL, *firstURL)
}
}
```
🥐 Now run `encore test ./...` to verify that it's working.
If you use the local development dashboard ([localhost:9400](http://localhost:9400)), you can even see traces for tests.
## 5. Deploy
## 2. Create monitor service
Let's start by creating the functionality to check if a website is currently up or down.
Later we'll store this result in a database so we can detect when the status changes and
send alerts.
🥐 Create an Encore service named `monitor` containing a file named `ping.go`.
```shell
$ mkdir monitor
$ touch monitor/ping.go
```
🥐 Add an Encore API endpoint named `Ping` that takes a URL as input and returns a response
indicating whether the site is up or down.
```go
-- monitor/ping.go --
// Service monitor checks if a website is up or down.
package monitor
import (
"context"
"net/http"
"strings"
)
// PingResponse is the response from the Ping endpoint.
type PingResponse struct {
Up bool `json:"up"`
}
// Ping pings a specific site and determines whether it's up or down right now.
//
//encore:api public path=/ping/*url
func Ping(ctx context.Context, url string) (*PingResponse, error) {
// If the url does not start with "http:" or "https:", default to "https:".
if !strings.HasPrefix(url, "http:") && !strings.HasPrefix(url, "https:") {
url = "https://" + url
}
// Make an HTTP request to check if it's up.
req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, err
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
return &PingResponse{Up: false}, nil
}
resp.Body.Close()
// 2xx and 3xx status codes are considered up
up := resp.StatusCode < 400
return &PingResponse{Up: up}, nil
}
```
🥐 Let's try it! Run `encore run` in your terminal and you should see the service start up.
Then 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.
You can then see the response, logs, and view a trace of the request. It will look something like this:
If you prefer to use the terminal instead run `curl http://localhost:4000/ping/google.com` in
a new terminal instead. Either way you should see the response:
```json
{"up": true}
```
You can also try with `httpstat.us/400` and `some-non-existing-url.com` and it should respond with `{"up": false}`.
(It's always a good idea to test the negative case as well.)
### Add a test
🥐 Let's write an automated test so we don't break this endpoint over time. Create the file `monitor/ping_test.go`
with the content:
```go
-- monitor/ping_test.go --
package monitor
import (
"context"
"testing"
)
func TestPing(t *testing.T) {
ctx := context.Background()
tests := []struct {
URL string
Up bool
}{
{"encore.dev", true},
{"google.com", true},
// Test both with and without "https://"
{"httpbin.org/status/200", true},
{"https://httpbin.org/status/200", true},
// 4xx and 5xx should considered down.
{"httpbin.org/status/400", false},
{"https://httpbin.org/status/500", false},
// Invalid URLs should be considered down.
{"invalid://scheme", false},
}
for _, test := range tests {
resp, err := Ping(ctx, test.URL)
if err != nil {
t.Errorf("url %s: unexpected error: %v", test.URL, err)
} else if resp.Up != test.Up {
t.Errorf("url %s: got up=%v, want %v", test.URL, resp.Up, test.Up)
}
}
}
```
🥐 Run `encore test ./...` to check that it all works as expected. You should see something like:
```shell
$ encore test ./...
9:38AM INF starting request endpoint=Ping service=monitor test=TestPing
9:38AM INF request completed code=ok duration=71.861792 endpoint=Ping http_code=200 service=monitor test=TestPing
[... lots more lines ...]
PASS
ok encore.app/monitor 1.660
```
And if you open the local development dashboard at [localhost:9400](http://localhost:9400), you can also see traces for the tests.
## 3. Create site service
Next, we want to keep track of a list of websites to monitor.
Since 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
library that makes building CRUD endpoints really simple.
🥐 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:
```shell
$ mkdir site
$ mkdir site/migrations
```
🥐 Add a database migration file inside that folder, named `1_create_tables.up.sql`.
The file name is important (it must look something like `1_
## Setting a Primary environment
Every Encore app has a configurable Primary environment that serves as the default for:
- App insights in the Encore Cloud dashboard
- API documentation
- CLI functionality (like API client generation)
**Configuring your Primary environment:**
1. Open your app in the [Encore Cloud dashboard](https://app.encore.cloud)
2. Navigate to **Settings** > **General** > **Primary Environment**
3. Select your desired environment from the dropdown
4. Click **Update**
================================================
FILE: docs/platform/deploy/own-cloud.md
================================================
---
seotitle: Connect your cloud account to deploy to any cloud
seodesc: Learn how to deploy your backend application to all the major cloud providers (AWS or GCP) using Encore.
title: Connect your cloud account
subtitle: Whatever cloud you prefer is fine by us
lang: platform
---
Encore Cloud lets you deploy your application to any of the major cloud providers, using your own cloud account.
This lets you use Encore to improve your experience and productivity, while keeping the reliability of a major cloud provider.
Each [environment](/docs/platform/deploy/environments) can be configured to use a different cloud provider, and you can have as many environments as you wish.
This also lets you easily deploy a hybrid or multi-cloud application, as you see fit.
## Frontend Collaboration
Preview 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.
This is a one-line change since your API client always specifies the environment name, e.g. `https://
#### Process allocation configuration
Encore 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.
It'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.)
Deploying each service as its own process will improve scalability and decrease blast radius if things go wrong. This is only recommended for production environments.
## Core Infrastructure Components
### Networking Architecture
To 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.
### Container Management
Encore Cloud provisions a [Google Container Registry (GCR)][gcp-gcr] to store your application's Docker images.
The 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.
Additionally, 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.
### Secrets Management
Encore 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.
## Compute Options
Encore Cloud provisions one of two compute platforms for running your application containers, based on your choice:
### Google Cloud Run
When using Cloud Run, Encore Cloud configures:
**Service Deployments**
Each 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.
**Cloud Run Services**
Cloud 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.
**IAM Configuration**
Each 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.
### Google Kubernetes Engine
When using GKE, Encore Cloud configures:
- **Cluster Setup**
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.
- **Kubernetes Resources**
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.
- **Load Balancer Integration**
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.
- **Monitoring Setup**
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.
- **Service Accounts**
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.
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.
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.
All 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.
## Managed Services
### Databases
Encore Cloud provisions [GCP Cloud SQL][gcp-cloudsql] for PostgreSQL databases, providing a robust and scalable database solution:
Encore 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.
Data 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.
Security 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.
### Pub/Sub
Encore 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.
### Object Storage
Encore 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.
### Caching
Encore 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.
### Cron Jobs
Encore 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.
[gcp-vpc]: https://cloud.google.com/vpc
[gcp-cloudrun]: https://cloud.google.com/run
[gcp-gke]: https://cloud.google.com/kubernetes-engine
[gcp-secrets]: https://cloud.google.com/secret-manager
[gcp-pubsub]: https://cloud.google.com/pubsub
[gcp-gcs]: https://cloud.google.com/storage
[gcp-cloudsql]: https://cloud.google.com/sql
[gcp-redis]: https://cloud.google.com/memorystore
[gcp-gcr]: https://cloud.google.com/container-registry
================================================
FILE: docs/platform/infrastructure/import-cloud-sql.md
================================================
---
seotitle: How to deploy your Encore application with an existing Cloud SQL instance
seodesc: Learn how to easily import your existing Cloud SQL instance and connect your Encore application to it.
title: Import an existing Cloud SQL instance
subtitle: Using your pre-existing database instead of provisioning a new one
lang: platform
---
# Overview
When 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.
## Benefits
Using an existing Cloud SQL instance allows you to:
- Maintain data continuity with your existing systems
- Preserve specific database configurations
- Utilize familiar database setups without migration
## Importing a Cloud SQL instance
Follow these steps to import your existing Cloud SQL instance:
1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)
2. Select the GCP cloud provider
3. Choose **Import Existing Cloud SQL Instance**
4. Add permissions for the Encore Service Account:
- Copy the `Encore GCP Service Account` from the cloud dashboard
- Go to your project's IAM page in the GCP Console
- Grant the `Owner` role to the `Encore GCP Service Account`
5. Return to the Encore Cloud dashboard
6. Specify your database's `GCP Project ID` and `Cloud SQL Instance Name`
7. Click the `Resolve` button to validate the instance
Once 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.
## Mapping existing databases to your Encore app
To 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:
```typescript
const db = new SQLDatabase("mydb");
```
```go
sqldb.NewDatabase("mydb", sqldb.DatabaseConfig{
Migrations: "./migrations",
})
```
## Applying migrations to existing databases
Encore 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:
```
version bigint
dirty boolean
```
If 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.
================================================
FILE: docs/platform/infrastructure/import-kubernetes-cluster.md
================================================
---
seotitle: How to deploy your Encore application to an existing Kubernetes cluster
seodesc: Learn how to easily import your existing Kubernetes cluster and deploy your Encore application into it.
title: Import an existing Kubernetes cluster
subtitle: Deploying to your pre-existing cluster instead of provisioning a new one
lang: platform
---
When 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.
If 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.
Kubernetes imports are supported on GCP, AWS support is coming soon.
## Importing a cluster
To 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`.
When you deploy to this environment, Encore Cloud will use your imported cluster as the compute instance.
================================================
FILE: docs/platform/infrastructure/import-project.md
================================================
---
seotitle: How to deploy your Encore application to an existing GCP project
seodesc: Learn how to easily import your existing GCP project and connect your Encore application to it.
title: Import an existing GCP project
subtitle: Using your pre-existing GCP project instead of provisioning a new one
lang: platform
---
# Overview
When 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.
## Benefits
Using an existing GCP project allows you to:
- Keep all your infrastructure in a single project
- Maintain existing IAM policies and permissions
- Utilize existing billing settings and quotas
- Consolidate resources for easier management
## Importing a GCP project
Follow these steps to import your existing GCP project:
1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)
2. Select the GCP cloud provider
3. Choose **Import Project**
4. Add permissions for the Encore Service Account:
- Copy the `Encore GCP Service Account` from the cloud dashboard
- Go to your project's IAM page in the GCP Console
- Grant the `Owner` role to the `Encore GCP Service Account`
5. Return to the Encore Cloud dashboard
6. Enter your `Project ID`
7. Click the `Resolve` button to validate the project
Once 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.
================================================
FILE: docs/platform/infrastructure/import-rds.md
================================================
---
seotitle: How to deploy your Encore application with an existing AWS RDS instance
seodesc: Learn how to easily import your existing AWS RDS instance and connect your Encore application to it.
title: Import an existing AWS RDS instance
subtitle: Using your pre-existing database instead of provisioning a new one
lang: platform
---
# Overview
When 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.
## Benefits
Using an existing AWS RDS instance allows you to:
- Maintain data continuity with your existing systems
- Preserve specific database configurations
- Utilize familiar database setups without migration
## Importing an AWS RDS instance
Follow these steps to import your existing AWS RDS instance:
1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)
2. Select the AWS cloud provider
3. Pick the `AWS Region` your database resides in
3. Choose **Import Existing RDS Instance**
4. Specify your database's `RDS Instance Name`
5. Click the `Resolve` button to validate the instance
Once 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.
## Mapping existing databases to your Encore app
To 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:
```typescript
const db = new SQLDatabase("mydb");
```
```go
sqldb.NewDatabase("mydb", sqldb.DatabaseConfig{
Migrations: "./migrations",
})
```
## Applying migrations to existing databases
Encore 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:
```
version bigint
dirty boolean
```
If 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.
================================================
FILE: docs/platform/infrastructure/infra.md
================================================
---
seotitle: Cloud Infrastructure Provisioning
seodesc: Learn how to provision appropriate cloud infrastructure depending on the environment type for AWS and GCP.
title: Infrastructure provisioning & Environments
subtitle: How Encore Cloud provisions infrastructure for your application
lang: platform
---
Encore 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.
## How it works
This 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.
At 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.
Encore 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.
The approach removes the need for infrastructure configuration files and avoids creating cloud-specific dependencies in your application.
Having 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.
## Environment types
By 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.
| | Local | Encore Cloud Hosting | GCP / AWS |
| ---------------------- | ------------------ | -------------------------- | ---------------------------------- |
| **Environment types:** | Development | Preview, Development | Development, Production |
| **Objectives:** | Provisioning speed | Provisioning speed, Cost\* | Reliability, Security, Scalability |
\*Encore Cloud Hosting is free to use, subject to Fair Use guidelines and usage limits. [Learn more](/docs/platform/management/usage)
## Development Infrastructure
Encore Cloud provisions infrastructure resources differently for each type of development environment.
| | Local | Preview / Development (Encore Cloud Hosting) | GCP / AWS |
| ------------------- | --------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
| **SQL Databases:** | Docker | Encore Cloud Managed (Kubernetes), [Neon](/docs/deploy/neon) | [See production](/docs/deploy/infra#production-infrastructure) |
| **Pub/Sub:** | In-memory ([NSQ](https://nsq.io)) | GCP Pub/Sub | [See production](/docs/deploy/infra#production-infrastructure) |
| **Caches:** | In-memory (Redis) | In-memory (Redis) | [See production](/docs/deploy/infra#production-infrastructure) |
| **Cron Jobs:** | Disabled | [Encore Cloud Managed](/docs/primitives/cron-jobs) | [See production](/docs/deploy/infra#production-infrastructure) |
| **Object Storage:** | Local Disk | Encore Cloud Managed | [See production](/docs/deploy/infra#production-infrastructure) |
### Local Development
For local development Encore Cloud provisions a combination of Docker and in-memory infrastructure components.
SQL Databases are provisioned using [Docker](https://docker.com). For Pub/Sub
and Caching the infrastructure is run in-memory.
When running tests, a separate SQL Database cluster is provisioned that is optimized for high performance
(using an in-memory filesystem and fsync disabled) at the expense of reduced reliability.
To avoid surprises during development, Cron Jobs are not triggered in local environments.
They can always be triggered manually by calling the API directly from the [development dashboard](/docs/ts/observability/dev-dash).
The application code itself is compiled and run natively on your machine (without Docker).
### Preview Environments
When 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.
Preview Environments are created in Encore Cloud Hosting, and are optimized for provisioning speed and cost-effectiveness.
The Preview Environment is automatically destroyed when the Pull Request is merged or closed.
Preview Environments are named after the pull request, so PR #72 will create an environment named `pr:72`.
### Encore Cloud Hosting
Encore Cloud Hosting is a simple, zero-configuration hosting solution provided by Encore.
It's perfect for development environments and small-scale use that do not require any specific SLAs.
It's also a great way to evaluate Encore Cloud without needing to connect your cloud account.
Encore Cloud Hosting is not designed for business-critical use and does not offer reliability guarantees for persistent storage
like SQL Databases. Other infrastructure primitives like Pub/Sub and Caching
are provisioned with small-scale use in mind.
[Learn more about the usage limitations](/docs/platform/management/usage)
## Production Infrastructure
Encore Cloud provisions production infrastructure resources using best-practice guidelines and services for each respective cloud provider.
| | GCP | AWS |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Networking:** | [VPC](/docs/platform/infrastructure/gcp#networking-architecture) | [VPC](/docs/platform/infrastructure/aws#networking-architecture) |
| **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) |
| **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) |
| **Pub/Sub:** | [GCP Pub/Sub](/docs/platform/infrastructure/gcp#pubsub) | [Amazon SQS & Amazon SNS](/docs/platform/infrastructure/aws#pubsub) |
| **Object Storage:** | [GCS/Cloud CDN](/docs/platform/infrastructure/gcp#object-storage) | [Amazon S3/CloudFront](/docs/platform/infrastructure/aws#object-storage) |
| **Caches:** | [GCP Memorystore (Redis)](/docs/platform/infrastructure/gcp#caching) | [Amazon ElastiCache (Redis)](/docs/platform/infrastructure/aws#caching) |
| **Cron Jobs:** | Encore Cloud Managed | Encore Cloud Managed | Encore Cloud Managed |
| **Secrets:** | [Secret Manager](/docs/platform/infrastructure/gcp#secrets-management) | [AWS Secrets Manager](/docs/platform/infrastructure/aws#se) |
### Configuration
With 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.
Learn more in the [Infrastructure Configuration](/docs/platform/infrastructure/configuration) documentation.
================================================
FILE: docs/platform/infrastructure/kubernetes.md
================================================
---
seotitle: How to deploy your Encore application to a new Kubernetes cluster
seodesc: Learn how to automatically deploy your Encore application to a new Kubernetes cluster.
title: Kubernetes deployment
subtitle: Deploying your app to a new Kubernetes cluster
lang: platform
---
# Deploying Encore Apps to Kubernetes
Encore Cloud gives you flexibility in where you run your applications. You have two options for Kubernetes deployments:
1. **Deploy to a new cluster**: Encore Cloud can automatically provision and manage a new Kubernetes cluster in your cloud account on AWS or GCP.
2. **Use an existing cluster**: Deploy to your pre-existing Kubernetes cluster ([see instructions here](/docs/platform/infrastructure/import-kubernetes-cluster))
All 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.
## Deploying to a new Kubernetes cluster
**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))
**2. Create environment:** Open your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to **Environments**, then click on **Create Environment**.
Next, 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.
You can also configure if you want to allocate all services in one process or run one process per service.
**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**.
**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.
**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.
## Infrastructure Overview
Encore 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.
### Namespace Management
Encore Cloud creates a unique namespace for each environment deployed to your Kubernetes cluster, ensuring complete isolation between different environments of your application.
### Secrets Management
Encore 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.
Service 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.
### Ingress Configuration
Encore 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.
## Service Management
### Deployments
Encore 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.
For 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.
### Network Configuration
Encore 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.
### Identity and Access
Encore 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.
For 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.
All 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.
================================================
FILE: docs/platform/infrastructure/manage-db-users.md
================================================
---
seotitle: Managing database user credentials
seodesc: Learn how to manage user credentials for databases created by Encore.
title: Managing database user credentials
lang: platform
---
Encore 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.
As an application **Admin**, open the [Encore Cloud dashboard](https://app.encore.cloud) and go to the **Infrastructure** page for the relevant environment.
In 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.
Note that databases hosted in [Encore Cloud](/docs/platform/infrastructure/infra#encore-cloud) currently do not expose usernames and passwords.
To connect to an Encore Cloud-hosted database, use [`encore db shell`](/docs/ts/primitives/databases#connecting-to-databases).
`encore db shell` defaults to read-only permissions. Use `--write`, `--admin` and `--superuser` flags to modify which permissions you connect with.
## Creating environments using Neon
Neon organizes databases in projects. A project consist of a main branch and any number of feature branches.
[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.
When configuring your Encore Cloud environment to use Neon, you can choose which project and branch to use. To get started,
head to the [Encore Cloud dashboard](https://app.encore.cloud) > (Select your app) > Environments > Create Environment. In the Database section, select
`Neon database`.
### Create a new Neon project and branch
If you're starting off a blank slate, you can let Encore Cloud create a new Neon project and branch for you.
Select `New Neon project` and choose a Neon account and region. We recommend picking a region close to your compute and
that you use the suggested project and branch names, but you're free to choose any configuration you like.
### Branch from an existing Encore Cloud environment
If you already have an Encore Cloud environment with Neon, you can branch your database from that environment.
Simply select `Branch from Encore environment` and choose the environment you want to branch from. This option will
be disabled if you don't have any environments using Neon.
### Branch from an existing Neon branch
You can also choose to manually select a Neon branch to branch from. This is useful if you have an existing Neon project,
but it's not currently being used by any Encore Cloud environments. Select `Branch from Neon project`,
then choose the account, project and branch you want to use.
### Import an existing Neon branch
The final option is to import an existing Neon branch. This is useful if you have an existing database you want to use.
Be wary that this option will not create a new branch but operate on the existing data. Select `Import Neon branch`,
then choose the account, project and branch you want to use.
**Note:** You may need to manually adjust the roles, commonly you need to change the database owner to the `db_
### Neon project
The retention history specifies how long Neon will keep changes to your data. The default is 1 day, but depending on your
Neon plan, you can increase this to up to 30 days.
### Neon endpoint
Each branch is assigned a unique endpoint which essentially is the serverless compute handling your database.
You can edit the endpoint to set the CPU limits and the suspend timeout. The suspend timeout is the time Neon will wait
before suspending the compute when it's not in use. The default is 5 minutes, but you can increase this to up to a week
(depending on your Neon plan).
## Use Neon for Preview Environments
Neon is a great choice for [Preview Environments](/docs/platform/deploy/preview-environments) as it allows you to branch off a populated
database and test your changes in isolation.
To configure which branch to use for Preview Environments, head to the
[Encore Cloud dashboard](https://app.encore.cloud) > (Select your app) > App Settings > Preview Environments
and select the environment with the database you want to branch from. Hit save and you're all done.
Keep 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.
When you come back to Encore, click the **Link App to GitHub** button:
In the popup, select the repository you would like to link your app with:
Click **Link** and you're done! Encore will now automatically start building and running tests against
your Pull Requests, and provision Preview Environments for each Pull Request.
## Placing your Encore app in a monorepo sub-folder
If 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.
Do 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.
## Configure deploy trigger
When using GitHub, you can configure Encore to automatically trigger deploys when you push to a specific branch name.
To 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.
## Preview Environments for each Pull Request
Once you've linked your app with GitHub, Encore will automatically start building and running tests against
your Pull Requests.
Encore will also provision a dedicated Preview Environment for each pull request.
This environment works just like a regular development environment, and lets you test your changes
before merging.
Learn more in the [Preview Environments documentation](/docs/platform/deploy/preview-environments).
================================================
FILE: docs/platform/integrations/oauth-clients.md
================================================
---
seotitle: Encore Cloud OAuth Clients
seodesc: Learn how to use OAuth Clients for access to the Encore Cloud API
title: OAuth Clients
lang: platform
---
OAuth 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.
## How it works
You create an OAuth client that defines the scopes to allow when your client application uses the Encore Cloud API.
Scopes are currently grouped into "roles", which include a set of permissions.
For example, the `deployer` role grants access to the triggering deployments.
An 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.
An 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.
OAuth client libraries in popular programming languages can handle the API access token generation and renewal.
Encore Cloud's OAuth implementation is based on the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749).
## Prerequisites
You need to be an Owner of the Encore application in order to create or revoke OAuth clients.
### Setting up an OAuth client
Open the OAuth clients page in the application settings page.
In the Generate OAuth client dialog, select the set of operations that can be performed with tokens created by the new OAuth client.
After 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.
Note that after you close the Generated new OAuth client dialog, you won't be able to copy the secret again.
**Store the client secret securely.**
Your 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.
If 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.
Application owners can see all configured OAuth clients in the OAuth clients page of the application settings.
### Roles
Roles define which operations are permitted in API access tokens that are created by your client application.
Currently there is a single supported role: **Deployer**. The deployer role
allows for programatically triggering deployments.
When new Encore Cloud functionality is provided, we will add it to existing roles where applicable.
That 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.
### Revoking an OAuth client
Open the OAuth clients page of the application settings page.
Find the OAuth client that you want to delete and select Revoke.
Select Revoke OAuth client to confirm you want to revoke the OAuth client.
When you revoke an OAuth client, any active API access tokens that were created by the client are also revoked.
### Encore Cloud OAuth token endpoint
Encore Cloud's OAuth token endpoint is https://api.encore.cloud/api/oauth/token.
See the [Encore Cloud API Reference](/docs/platform/integrations/api-reference) documentation for more information.
Make 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.
## OAuth client libraries
Popular programming languages provide OAuth client libraries to simplify your use of OAuth clients.
For 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.
Similar libraries exist for other popular programming languages.
```go
package main
import (
"context"
"os"
"golang.org/x/oauth2/clientcredentials"
)
func main() {
oauthConfig := &clientcredentials.Config{
ClientID: os.Getenv("OAUTH_CLIENT_ID"),
ClientSecret: os.Getenv("OAUTH_CLIENT_SECRET"),
TokenURL: "https://api.encore.cloud/api/oauth/token",
}
client := oauthConfig.Client(context.Background())
// Make API calls using `client.Get` etc.
resp, err := client.Get("https://api.encore.cloud.com/api/...")
// ...
}
```
The 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.
### Verifying you can generate API access tokens
After 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.
```bash
curl -d "client_id=${OAUTH_CLIENT_ID}" -d "client_secret=${OAUTH_CLIENT_SECRET}" \
-d "grant_type=client_credentials" "https://api.encore.cloud/api/oauth/token"
```
The 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.
Here's an example response showing the API access token:
```json
{"access_token":"MTcyODQ3NTg3NXww...GDxfmxnuq9zDEAmHmP5D44=","token_type":"Bearer","expires_in":3600, "actor": "o2c_my_key_id"}
```
## Limitations
An OAuth access token expires after 1 hour — this duration cannot be modified.
================================================
FILE: docs/platform/integrations/terraform.md
================================================
---
seotitle: Integrate Encore with existing infrastructure
seodesc: The Encore Terraform Provider lets you integrate your Encore deployment with existing infrastructure
title: Terraform Provider
subtitle: Integrate Encore with existing infrastructure
infobox: {
title: "Terraform Provider",
import: "https://registry.terraform.io/providers/encoredev/encore",
}
lang: platform
---
Encore 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.
## Understanding Encore Terraform Data Sources
Encore Terraform data sources act as read-only references to resources Encore has already provisioned on your behalf.
Unlike Terraform resources (which create or modify infrastructure), data sources only retrieve information. The Encore
data sources let's you retrieve cloud identifiers for resources managed by Encore, such as databases, caches, and more.
To do this, you only need to provide the name of the resource and the environment it's in.
## Configuring the Encore Terraform Provider
To use Encore data sources, you need to declare the Encore Terraform provider in the `required_providers` of
your Terraform configuration file. Here's an example of how to declare the provider:
```
terraform {
required_providers {
encore = {
source = "registry.terraform.io/encoredev/encore"
}
}
}
```
Once you've declared the provider, Terraform will automatically download the provider plugin when initializing the
working directory using `terraform init`.
To authenticate with the Encore API, the provider need an Encore Auth Key. You can generate an auth key from
Encore's [Cloud Dashboard](https://encore.dev/docs/platform/integrations/auth-keys). Once you have the auth key, you can configure the
provider in your Terraform configuration file like this:
```
provider "encore" {
env = "your-env"
auth_key = "your-auth-key"
}
```
You can also set the `ENCORE_AUTH_KEY` environment variable to avoid hardcoding the auth key in your configuration file.
## Using Encore Terraform Data Sources
Once you have the provider configured, you can use the Encore data sources to retrieve information about resources.
There are several data sources available, such as `encore_database`, `encore_cache`, and `encore_pubsub_topic`. Each data
source has its own set of attributes that you can use to retrieve information about the resource. The full documentation
for each data source is available in the [Terraform Registry](https://registry.terraform.io/providers/encoredev/encore).
Here's an example of how to use the `encore_pubsub_topic` data source to connect AWS IOT Core to an Encore PubSub topic:
```
data "encore_pubsub_topic" "topic" {
name = "my-topic"
env = "my-env"
}
resource "aws_iot_topic_rule" "rule" {
name = "my-rule"
sql = "SELECT * FROM 'my-topic'"
sns {
message_format = "RAW"
role_arn = aws_iam_role.role.arn
target_arn = data.encore_pubsub_topic.topic.aws_sns.arn
}
}
```
================================================
FILE: docs/platform/integrations/webhooks.md
================================================
---
seotitle: Subscribe to Encore Cloud webhooks and events
seodesc: Encore Cloud lets you define webhooks to react to events in your application, enabling you to build powerful integrations.
title: Webhooks & Events
subtitle: Set up webhooks to react to Encore events
infobox: {
title: "Webhooks",
import: "go.encore.dev/webhooks",
}
lang: platform
---
Webhooks provide a way for notifications to be delivered to an HTTP endpoint of your choice whenever certain events happen within Encore.
For example, you can set up a webhook to be notified whenever a deployment starts or finishes.
Webhooks are defined on a per-application basis, and are configured under Settings -> Webhooks in the [Encore Cloud dashboard](https://app.encore.cloud).
To simplify using webhooks, Encore.go provides a Go module, [go.encore.dev/webhooks](https://pkg.go.dev/go.encore.dev/webhooks), that provides
type definitions and documentation of all supported webhook events. This module is kept up to date as new events are added.
## Webhook Deliveries
Each time an event occurs that matches one of your defined webhooks,
Encore will send a HTTP POST request to the webhook's configured URL with information about the event.
If the HTTP request fails, the delivery is marked as failed and won't be retried.
Each event is given a unique event id, which is shared across all webhooks.
Within each webhook, each event is given a sequence number, which is incremented for each event
that matches that webhook. The sequence number allows for a linear ordering of events within a webhook,
making it easy to determine if an event was missed.
These are provided in the `X-Encore-Event-Id` and `X-Encore-Sequence-Id` headers respectively,
and are also part of the event payload itself.
## Parsing webhook events
To parse a webhook event, use the [`webhooks.ParseEvent`](https://pkg.go.dev/go.encore.dev/webhooks#ParseEvent) function.
As you'll see in the example below, to parse the webhook event you'll need access to the webhook secret.
This is a secret value that is generated by Encore and is used to sign each webhook request. More about this
in the next section.
For example, to process rollout started and completed webhook events,
you could do something like this:
```go
package service
import (
"net/http"
"go.encore.dev/webhooks"
)
var secrets struct {
EncoreWebhookSecret string
}
//encore:api public raw
func Webhook(w http.ResponseWriter, req *http.Request) {
payload, err := io.ReadAll(req.Body)
if err != nil {
// ... handle error
}
event, err := webhooks.ParseEvent(payload, req.Header.Get("X-Encore-Signature"), secrets.EncoreWebhookSecret)
if err != nil {
// ... handle error
}
switch data := event.Data.(type) {
case *webhooks.RolloutCreatedEvent:
// ... handle rollout created event
case *webhooks.RolloutCompletedEvent:
// ... handle rollout completed event
}
}
```
Encore 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.
The 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.
With 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.
The 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!_
Aside from managing infrastructure, Encore's local development workflow comes with a lot of tools to make building distributed systems easier:
- **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.
- **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.
- **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.
- **Tracing:** The [local development dashboard](/docs/ts/observability/dev-dash) provides local tracing to help understand application behavior and find bugs.
- **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.
## Testing
Encore's open source framework comes with several built-in tools to help with testing:
- **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.
- **Local test infra:** When running tests locally, Encore automatically provides dedicated [test infrastructure](/docs/go/develop/testing#test-only-infrastructure) to isolate individual tests.
- **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.
Encore Cloud adds to this tool-set with:
- **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.
## Infrastructure & DevOps automation
### Infrastructure Management
- **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.
- **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.
- **No IaC required:** Say goodbye to Terraform and YAML - your code is the single source of truth.
### Security & Governance
- **Automated IAM:** Least-privilege security permissions generated from parsing your code
- **Infrastructure tracking:** Complete visibility of all provisioned resources
- **Change management:** Built-in approval workflow for infrastructure changes
- **Configuration management:** Simple UI for config changes that automatically 2-way syncs to your cloud
### Monitoring & Observability
- **Cost monitoring:** Track infrastructure costs across your cloud resources (currently for GCP, AWS coming soon)
- **Integrated observability:** Built-in logging, metrics, and tracing
- **Third-party integration:** Works with Datadog, Grafana, and other tools
- **Auto-generated documentation:**
- Service catalog with complete API docs
- Live architecture diagrams showing infrastructure dependencies
## Why choose Encore Cloud?
Encore Cloud's end-to-end workflow is an unfair advantage for teams that need to move quickly without sacrificing quality and scalability.
By 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.
The benefits of Encore Cloud are:
- **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.
- **Reduced Costs**: Encore Cloud's infrastructure management minimizes wasteful cloud expenses and reduces DevOps workload by 90%.
- **Scalability & Performance**: Encore Cloud simplifies building microservices applications that can handle growing user bases and demands, without the normal boilerplate and complexity.
- **Control & Standardization**: Encore Cloud enforces standardization and provisions infrastructure consistently according to best practices for each cloud provider.
- **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.
- **Security**: Encore Cloud makes your application secure by automatically implementing security best practices for each cloud provider.
## Common use cases
Encore Cloud is designed to give teams a productive and less complex experience when solving most common backend use cases.
Many teams use Encore Cloud to build things like:
- Consumer apps
- High-performance B2B Platforms
- Fintech & Crypto applications
- Global E-commerce marketplaces
- Microservices backends and event-driven systems for scalable SaaS applications
- And much more...
Check out the [showcase](https://encore.cloud/showcase) section for some examples of real-world products being built with Encore.
## Getting started
- [Follow the Quick Start Guide](/docs/ts/quick-start)
- [Join Discord](https://encore.dev/discord) to ask questions and meet other Encore developers
- Follow and star the project on [GitHub](https://github.com/encoredev/encore) to stay up to date
- [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
================================================
FILE: docs/platform/management/billing.md
================================================
---
seotitle: Plans & Billing
seodesc: Encore is free to use for many projects, and comes with paid plans for teams who want to move quickly. Learn more!
title: Plans & Billing
subtitle:
lang: platform
---
Encore offers a **Free** plan for teams that want a simple development workflow and collaboration features.
If 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.
See the [pricing page](https://encore.dev/pricing) for a feature comparison between each plan and complete pricing information.
## When do I need to upgrade to a paid plan?
The 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:
- When you need more than 2 cloud environments
- When you want to [automate DevOps in your cloud on AWS/GCP](/docs/platform/infrastructure/infra)
- When you want [Preview Environments](/docs/platform/deploy/preview-environments) for each Pull Request
- When you want to use a Custom Domain
- When you need multiple concurrent builds
- When you need guaranteed logs & tracing retention
- When you want access to private support & onboarding assistance
- When you want custom configuration for environments hosted on Encore Cloud
There 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.
You can activate your trial from the [pricing page](https://encore.dev/pricing).
## Do I need to pay for hosting?
All plans come with free use of Encore Cloud, subject to [Fair Use limits](/docs/platform/management/usage).
Encore Cloud is intended for development environments and limited scale professional use that does not require specific SLAs.
For 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.
If 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))
## Payments & Billing FAQ
### What is the price of the paid plan?
See the [pricing page](https://encore.dev/pricing) for complete pricing information.
If 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.
### Can I pay with a credit card?
Yes, we offer payments via Stripe using all major credit cards. You can upgrade your account via the [pricing page](/pricing).
### What happens if my payment fails?
If your payment fails, everything will keep working as normal!
We will reach out to you with instructions on how to update your payment information so that we can try to process your payment again.
We will not downgrade your account without prior notice.
================================================
FILE: docs/platform/management/compliance.md
================================================
---
seotitle: Security & Compliance
seodesc: Learn about Encore's security practices, infrastructure protections, and compliance posture — built on industry-standard controls and trusted cloud providers.
title: Security & Compliance
subtitle: How Encore protects your applications, code, and data
lang: platform
---
_Last updated: March 3, 2026_
Your 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.
### Security at a glance
| Area | What we do |
| --- | --- |
| **Infrastructure** | Hosted on GCP (ISO 27001 / SOC 2 certified). All servers are private, accessible only via VPN. |
| **Encryption** | AES-256 at rest, TLS 1.2+ and WireGuard in transit. Customer secrets additionally encrypted via GCP KMS. |
| **Zero-trust networking** | All server-to-server communication is authenticated and end-to-end encrypted via Tailscale / WireGuard. |
| **Access control** | Principle of least privilege, MFA enforced, regular access reviews, VPN-only infrastructure access. |
| **Authentication** | Managed by Clerk (SOC 2 certified). Passwordless by default — Encore never stores or handles user passwords. |
| **Monitoring & alerting** | 24/7 monitoring via Grafana, Sentry, Cronitor, and GCP Cloud Monitoring (all SOC 2 certified). |
| **Vendor security** | All critical vendors are SOC 2 and/or ISO 27001 certified (GCP, Tailscale, Clerk, GitHub, Sentry, Grafana). |
| **Code quality** | Mandatory code review, CI/CD with automated testing, automated vulnerability scanning. |
| **Data privacy** | GDPR compliant. Data minimization by design. |
| **Responsible disclosure** | Active bug bounty program for security researchers. |
## SOC 2
SOC 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.
After the Type 1 audit, we plan to proceed to Type 2, which involves continuous monitoring over an extended period.
### Trust Service Criteria
The five SOC 2 trust service criteria are: security, availability, confidentiality, processing integrity, and privacy.
**1\. Security**
Protecting systems against unauthorized access.
**2\. Availability**
Ensuring that the system remains functional and usable.
**3\. Confidentiality**
Restricting 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.
**4\. Processing integrity**
Ensuring that a system fulfills its purpose and delivers correct data.
**5\. Privacy**
Minimal processing and use of personal data in accordance with the law.
The following sections describe in detail how Encore implements each trust service principle.
## Security
We 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.
We have a designated Security Officer responsible for all aspects of security across infrastructure, software, and data.
### Infrastructure security
Encore'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.
All 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.
Access 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.
The 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.
### Organizational security
An 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.
Employees 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.
Encore employment policy mandates full-disk encryption on all employee devices.
### Product security
Multiple layers of protection ensure that customer data is not accessible to unauthorized persons.
Encore'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.
As 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).
All 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.
User account authentication is provided by _Clerk_, a SOC 2 compliant vendor.
There 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.
If 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.
Encore 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.
All security issues undergo a triaging process by the Security Officer and are escalated based on criticality.
### Responsible disclosure
We 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.
### Access control
We 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.
Offboarding 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.
#### MFA
Multi-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.
Stealing 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.
Usually, 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.
## Availability
Hosted 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.
During 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.
### Performance monitoring
Encore 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.
Slack, 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.
Encore 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/).
### Backups and disaster recovery
To 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.
Encore 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.
### Incident handling
Whenever 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.
Customers 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.
## Confidentiality
When 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.
### Access controls
All employees and contractors are contractually bound to confidentiality, which persists after the termination of the work contract.
As 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.
All 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.
### Deletion
User 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.
## Processing integrity
### Quality assurance
Product quality is very important to Encore. There are many different facets, including:
- Accuracy and usability of services provided
- High performance of the user interface and Encore services
- Almost zero downtime
Several measures are put into place in order to keep product quality high:
- 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.
- 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.
- 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.
- 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.
- 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.
Any 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.
Since 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.
### Process monitoring
Where possible, Encore uses software to enforce processes. For example, code review and having tests passed are enforced by the source control management tool GitHub.
Regular reviews on different levels (individual, team, company) foster alignment between all individuals and the company objectives.
### Privacy
Encore 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.
One 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.
### Privacy policy
We 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.
## Questions and further information
We 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).
================================================
FILE: docs/platform/management/permissions.md
================================================
---
seotitle: Roles & Permissions
seodesc: Encore helps your whole team build applications and collaborate across backend and frontend teams.
title: Roles & Permissions
subtitle: For teams building applications together
lang: platform
---
Encore applications have three membership roles with different permissions: **Admins**, **Members**, and **Viewers**.
Here is a breakdown of the key differences between each role:
| | Admins | Members | Viewers |
| ----------------------------------- | ------ | ------- | ------- |
| Manage team members | Y | N | N |
| Connect/Disconnect cloud accounts | Y | N | N |
| Integrate with GitHub | Y | N | N |
| Configure custom domains | Y | N | N |
| Manage environments | Y | N | N |
| Create auth keys | Y | N | N |
| Approve infrastructure provisioning | Y | N | N |
| Delete applications | Y | N | N |
| Push code changes | Y | Y | N |
| Create builds & deployments | Y | Y | N |
| Configure secrets | Y | Y | N |
| Pull secrets | Y | Y | Y |
| Run locally | Y | Y | Y |
| View API documentation | Y | Y | Y |
| View Encore Flow | Y | Y | Y |
### Admins
Admins have full privileges and can administer your entire application.
### Members
Members are active contributors to your applications. They are able to do everything that is not limited to Admins.
### Viewers
Viewers are read-only members. They can view the Cloud Dashboard and run your application locally.
This 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.
### Custom roles & permissions
Custom roles & permissions is an optional add-on to the [Pro plan](/pricing), please [contact us](mailto:hello@encore.dev) to discuss your requirements.
================================================
FILE: docs/platform/management/telemetry.md
================================================
---
seotitle: Encore Telemetry
seodesc: Encore collects telemetry data about app usage
title: Telemetry
lang: platform
---
Telemetry 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.
Encore 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.
## Why We Collect Data
We collect telemetry data for several important reasons:
1. **Improvement of Features**: Understanding which features are most used helps us prioritize improvements and new feature development.
2. **Performance Monitoring**: Tracking performance metrics enables us to identify and resolve issues, ensuring a smoother user experience.
3. **Bug Detection**: Telemetry data can help us detect and fix bugs faster by providing context on how and when issues occur.
4. **User Experience**: Insights from telemetry data guide us in making Encore more intuitive and user-friendly.
## How Data is Collected
Encore collects data in a way that prioritizes user privacy and security. Here's how we do it:
1. **User Identifiable Data**: The data collected includes identifiable information that helps us understand specific user interactions and contexts.
2. **Types of Data**: We collect data on usage patterns, performance metrics, and error reports.
3. **Secure Transmission**: All data is transmitted securely using industry-standard encryption protocols.
4. **Minimal Impact**: Data collection is designed to have minimal impact on Encore's performance.
### Example of Data Being Sent
Here is an example of the type of data that is sent:
```json
{
"event": "app.create",
"anonymousId": "a-uuid-unique-for-the-installation",
"properties": {
"error": false,
"lang": "go",
"template": "graphql"
}
}
```
## Data We Don't Collect
At Encore, we prioritize your privacy and ensure that no sensitive data is collected through our telemetry. Specifically, we do not collect:
1. **Environment Variables**: We do not collect any environment variables set in your development or production environments.
2. **File Paths**: The specific paths of your files and directories are not collected.
3. **Contents of Files**: We do not access or collect the contents of your code files or any other files in your projects.
4. **Logs**: No log files from your application or development environment are collected.
5. **Serialized Errors**: We do not collect serialized errors that may contain sensitive information.
Our goal is to gather useful data that helps improve Encore while ensuring that your sensitive information remains private and secure.
## Disabling Telemetry
While 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:
1. **Using the CLI Command**: You can disable telemetry by executing a simple command in your terminal.
```sh
encore telemetry disable
```
2. **Setting an Environment Variable**: Alternatively, you can disable telemetry by setting the `DISABLE_ENCORE_TELEMETRY` environment variable.
```sh
export DISABLE_ENCORE_TELEMETRY=1
```
3. **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.
4. **Re-enabling Telemetry**: If you decide to re-enable telemetry later, you can do so with the following CLI command:
```sh
encore telemetry enable
```
## Debugging Telemetry
For users who want more visibility into what telemetry data is being sent, you can enable debug mode:
1. **Setting Debug Mode**: Enable debug mode by setting the `ENCORE_TELEMETRY_DEBUG` environment variable.
```sh
export ENCORE_TELEMETRY_DEBUG=1
```
2. **Log Statements**: When debug mode is enabled, a log statement prepended by `[telemetry]` will be printed every time telemetry data is sent.
## Conclusion
Telemetry 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.
Thank you for helping us make Encore better!
================================================
FILE: docs/platform/management/usage.md
================================================
---
seotitle: Usage limits and Fair Use guidelines
seodesc: 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.
title: Usage limits
subtitle: Encore Cloud limits and Fair Use guidelines
lang: platform
---
Encore 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.
Encore Cloud is subject to Fair Use guidelines and comes without warranty, as it's not intended for large-scale business-critical use cases.
For 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).)
When you use Encore together with AWS/GCP, you can still use Encore Cloud to host Preview Environments and development environments.
### Examples of Fair Use
- Prototyping & development
- Hobby projects
- Commercial use cases that have limited load and do not require any SLAs
### Never Fair Use
- Proxies and VPNs
- Media hosting for hot-linking
- Scrapers
- Crypto Mining
- CPU-intensive APIs (e.g.: Machine Learning)
- Load Testing
## Usage guidelines
We expect most users to fall within the usage limits below.
We want to be as flexible and permissive as possible, and will wherever possible reach out and work with you
to find a good solution should we notice that you are exceeding these limits.
For users on a [paid plan](/pricing), we can change these limits to support your needs. If you have significantly higher requirements,
this may come with an additional charge (at cost) to cover the extra capacity. Please [contact us](/book) for more information.
**We will never charge you for usage of Encore Cloud unless expressly agreed in advance.**
### Usage limits
| | Per application |
| ---------------- | --------------- |
| Requests | 100,000 / day |
| Database Storage | 1 GB |
| PubSub Messages | 100,000 / day |
| Cron Jobs | Once every hour |
| Object Storage | 1 GB |
### What happens if I reach a usage limit?
If 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.
================================================
FILE: docs/platform/migration/migrate-away.md
================================================
---
title: Migrate away from Encore
subtitle: If you love someone, set them free.
lang: platform
---
_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._
Picking 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.
When 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.
In 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.
## Accommodating for your unique requirements
Many 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:
- You can drop down in abstraction level in the API framework using [raw endpoints](/docs/ts/primitives/defining-apis#raw-endpoints)
- You can use tools like the [Terraform provider](/docs/platform/integrations/terraform) to integrate infrastructure that is not managed by Encore
## Mitigating risk through Open Source and efficiency
We believe that adopting Encore is a low-risk decision for several reasons:
- There's no upfront investment needed to get the benefits
- Encore apps are normal programs where less than 1% of the code is Encore-specific
- All infrastructure and data is in your own cloud
- It's simple to integrate with cloud services and systems not natively supported by Encore
- 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)
- Everything you need to self-host your application is [Open Source and documented](/docs/ts/self-host/build)
## What to expect when migrating away
If 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.
### Code changes
Building 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.
This 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.
### Deployment
If you are self-hosting your application, then you're already done.
If 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.
Learn more in the [self-hosting docs](/docs/ts/self-host/build).
### Tell us what you need
We're engineers ourselves and we understand the importance of not being constrained by a single technology.
We're working every single day on making it even easier to start, and stop, using Encore.
If you have specific concerns, questions, or requirements, we'd love to hear from you!
Please reach out on [Discord](https://encore.dev/discord) or [send an email](mailto:hello@encore.dev) with your thoughts.
================================================
FILE: docs/platform/migration/migrate-to-encore.md
================================================
---
title: Migrating an existing system to Encore
subtitle: Approaches for adopting Encore
seotitle: How to migrate your existing system to Encore
seodesc: Learn how to migrate your application to Encore incrementally, and unlock Encore's powerful set of development tools for your team.
lang: platform
---
By 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).
**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.
## Why incremental migration?
Incremental migration is more reliable than a complete rewrite. Here's why:
- **Immediate value** - Start benefiting from Encore's features when developing your next new service.
- **Lower risk** - Small, controlled changes instead of a single high-stakes big-bang launch.
- **Ship faster** - Deliver improvements incrementally rather than waiting for a complete rewrite.
## Choose your migration strategy
We recommend two approaches:
1. **Service by service** (Recommended) - Migrate services one at a time. Run Encore alongside your legacy system, integrated via APIs.
2. **Forklift migration** - Move your entire application in one shot using a catch-all handler, then refactor incrementally.
### Need help?
We've helped 100+ teams adopt Encore and we're happy to answer your questions and provide advice to help you with your migration.
[Email us](mailto:hello@encore.dev) to ask questions, or [book a 1:1 call](https://encore.dev/book) to discuss your specific situation.
**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.
## Service by service migration (Recommended)
Migrate services one at a time while your Encore application runs alongside your legacy system, integrated through APIs.
### Key benefits
- **Full Encore features immediately** - Get automatic infrastructure provisioning, distributed tracing, and architecture diagrams for each migrated service.
- **Independent services** - Each service is self-contained with no cross-application dependencies.
- **Simple integration** - Services communicate via APIs.
- **Flexible deployment** - Deploy to your existing Kubernetes cluster, or let Encore Cloud set up a new project in your cloud (AWS/GCP).
- **Better developer experience** - Start building with modern tooling right away.
### Deployment options
Choose how to deploy your Encore application:
- **Your Kubernetes cluster** - Deploy directly to your existing Kubernetes infrastructure. Run Encore alongside legacy systems securely in the same environment.
- **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.
**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.
_Google Cloud example architecture:_
Next, open the environment **Overview** for the environment you wish to sent metrics from and click on **Settings**.
Then in the **Sending metrics data** section, select your Grafana Cloud Stack from the drop-down and save.
That's it! After your next deploy, Encore will start sending metrics data to your Grafana Cloud Stack.
Next, open the environment **Overview** for the environment you wish to sent metrics from and click on **Settings**.
Then in the **Sending metrics data** section, select your Datadog Account from the drop-down and save.
## Enabling Worker Pooling
To enable Worker Pooling, add `"build": {"worker_pooling": true}` to your `encore.app` file.
## Designing your application to work with Worker Pooling
Most application code will work with Worker Pooling without any changes. However, it's important to understand
the implications of running in a multi-threaded environment.
When utilizing Worker Pooling, Encore.ts will automatically spin up multiple NodeJS isolates (one per CPU) to handle incoming requests.
Each NodeJS isolate is a separate JavaScript runtime, with its own event loop and memory space.
This means that you cannot rely on global shared state that is shared across all incoming requests,
since each request may be handled by a different NodeJS isolate.
================================================
FILE: docs/ts/develop/orms/drizzle.md
================================================
---
seotitle: Using Drizzle with Encore
seodesc: Learn how to use Drizzle with Encore to interact with SQL databases.
title: Using Drizzle ORM with Encore
lang: ts
---
Encore.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.
-
{query.data?.map((todo) => (
- {todo.title} ))}
Person Page
Name: <%= name %>
``` ## Serving from a dynamic path This 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`. ```ts import { api } from "encore.dev/api"; import { APICallMeta, currentRequest } from "encore.dev"; import ejs, { Options } from "ejs"; const BASE_PATH = "./template/views"; const ejsOptions: Options = { views: [BASE_PATH] }; export const servePathTemplate = api.raw( { expose: true, path: "/!path", method: "GET" }, async (req, resp) => { const { path } = (currentRequest() as APICallMeta).pathParams; const viewPath = `${BASE_PATH}/${path ?? "index"}.html`; const html = await ejs.renderFile(viewPath, ejsOptions); resp.setHeader("content-type", "text/html"); resp.end(html); }, ); ``` ## Serving inline HTML In this example we are serving inline HTML with EJS. We use the `ejs.render` function to render the inline HTML with the given data. ```ts import { api } from "encore.dev/api"; import ejs, { Options } from "ejs"; const inlineHTML = `