Quick Start Guide
Get started building with Encore in minutes
In this short guide, you'll learn key concepts and experience the Encore workflow. It should only take about 5 minutes to complete and by the end you'll have an API running in Encore's free development Cloud (Encore Cloud).
To make it easy to follow along, we've laid out a trail of croissants to guide your way. Whenever you see a 🥐 it means there's something for you to do.
Let's get started!
1. Install the Encore CLI
To develop with Encore, you need the Encore CLI. It provisions your local environment, and runs your local development dashboard complete with tracing and API documentation.
🥐 Install by running the appropriate command for your system:
$ brew install encoredev/tap/encore
2. Create your app
🥐 Create your app by running:
$ encore app create
Since this is the first time you're using Encore, you'll be asked to create a free account. This is needed so that Encore can orchestrate functionality like tracing, secrets, and manage cloud deployments. You can use your account with GitHub, Google, or create an account using your email.
🥐 Continue by picking a name for your app and select the Hello World
template.
This will create an example application, with a simple REST API, in a new folder using the app name you picked.
Let's take a look at the code
Part of what makes Encore different is the simple developer experience when building distributed systems. Let's look at the code to better understand how to build applications with Encore.
🥐 Open the hello.go
file in your code editor. It's located in the folder: your-app-name/hello/
.
You should see this:
package hello
import (
"context"
)
// This is a simple REST API that responds with a personalized greeting.
//
//encore:api public path=/hello/:name
func World(ctx context.Context, name string) (*Response, error) {
msg := "Hello, " + name + "!"
return &Response{Message: msg}, nil
}
type Response struct {
Message string
}
As you can see, it's all standard Go code except for a few lines specific to Encore's Infrastructure SDK.
One such element is the API annotation:
//encore:api public path=/hello/:name
This annotation is all that's needed for Encore to understand that this Go package is a service, hello
, and that the World
function is a public API endpoint.
If you want to create more services and endpoints, you simply create new Go packages and define endpoints using the //encore:api
annotation. If you're curious, you can read more about defining services and APIs.
Encore's Infrastructure SDK provides several declarative ways of using backend primitives like databases, Pub/Sub, and scheduled tasks by simply writing code.
3. Start your app & Explore Local Development Dashboard
🥐 Now let's run your app locally:
$ cd you-app-name # replace with the app name you picked$ encore run
You should see this:
That means your local development environment is up and running! Encore takes care of setting up all the necessary infrastructure for your applications, including databases.
🥐 While you keep the app running, open a separate terminal and call your API endpoint:
$ 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!
Open the Local Development Dashboard
You can now start using your Local Development Dashboard.
🥐 Open http://localhost:9400 in your browser to access it.
The Local Development Dashboard is a powerful tool to help you move faster when you're developing new features.
It comes with an API explorer with automatically generated documentation, and powerful oberservability features like distributed tracing. Did we mention Encore automatically instruments your entire application with logs and tracing?
Through the Local Development Dashboard you also have access to Encore Flow which is a visual representation of your microservice architecture that updates in real-time as you develop your application.
4. Push a code change and deploy
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:
Changes detected, recompiling... Reloaded successfully. INF registered endpoint endpoint=World path=/hello/:name service=hello INF listening for incoming HTTP requests
🥐 Test your change by calling your API in a separate terminal:
$ curl http://localhost:4000/hello/world{"Message": "Howdy, world!"}
Great job, you're now ready to head to the cloud!
Deploy your app to the cloud
The first time you deploy, Encore will by default create a staging environment in Encore's free development cloud (Encore Cloud).
Later, when you are ready to create a production environment you can deploy to your own cloud account with GCP and AWS. (Or even all of them, Encore makes it seamless to deploy to multiple cloud environments all at once.)
🥐 Now push your changes and deploy your application by running:
$ git add -A .$ git commit -m 'Initial commit'$ git push encore
Encore will now build and test your app, provision the needed infrastructure, and deploy your application to the cloud.
Your app will soon be running in the cloud, isn't this exciting?
5. Explore the Cloud Dashboard
After triggering the deployment, you will see a URL where you can view its progress in Encore's Cloud Dashboard.
It will look something like: https://app.encore.dev/$APP_ID/deploys/...
🥐 Open the URL to access the Cloud Dashboard and check the progress of your deployment.
You can now use the Cloud Dashboard to view production logs and traces, create new environments, connect the cloud account of your choice, integrate with GitHub, and much more.
Call your API in the cloud
Now that you've created your staging environment, you're ready to call your API running in the cloud.
Your API Base URL will be something like: https://staging-$APP_ID.encr.app
🥐 When the deploy is finished, call your API from the terminal (replacing $APP_ID
with your own App ID):
$ curl https://staging-$APP_ID.encr.app/hello/world{"Message": "Howdy, world!"}
If you see this you've successfully made an API call to your very first Encore app running in the cloud.
Congratulations, you're well on your way to escaping the maze of cloud complexity!
What's next?
🥐 Check out the Uptime Monitor tutorial to learn how to add more services, use databases, PubSub, and cron jobs.
If you want to chat to other pioneering developers already building with Encore, or need help, join the friendly community on Slack.