How to deploy a backend application to DigitalOcean using Docker and Encore

💡 This guide shows you how to deploy an Encore application to DigitalOcean using the new encore build command, part of Encore's open source CLI.

This is handy if you prefer manual deployment over the automation offered by Encore's Cloud Platform.

Even when deploying manually, Encore simplifies the process by providing tools to build and configure your app.⚡️

Now let's take a look at how to deploy an Encore app to DigitalOcean's App Platform using Docker and encore build.🚀

Prerequisites

• DigitalOcean Account: Make sure you have a DigitalOcean account. If not, you can sign up here.
• Docker Installed: Ensure Docker is installed on your local machine. You can download it from the Docker website.
• Encore CLI: Install the Encore CLI:
  • macOS: brew install encoredev/tap/encore
  • Linux: curl -L https://encore.dev/install.sh | bash
  • Windows: iwr https://encore.dev/install.ps1 | iex
• DigitalOcean CLI (Optional): You can install the DigitalOcean CLI for more flexibility and automation, but it’s not necessary for this tutorial.

Step 1: Create an Encore App

• Create a New Encore App:

  • If you haven’t already, create a new Encore app using the Encore CLI.
  • You can use the following command to create a new app:

  encore app create myapp
  

  • Select the Hello World template.
  • Follow the prompts to create the app.

• Build a Docker image:

  • Build the Encore app to generate the docker image for deployment:

  encore build docker myapp  
  

Step 2: Push the Docker Image to a Container Registry

To deploy your Docker image to DigitalOcean, you need to push it to a container registry. DigitalOcean supports
its own container registry, but you can also use DockerHub or other registries. Here’s how to push the image to DigitalOcean’s registry:

• Create a DigitalOcean Container Registry:

  • Go to the DigitalOcean Control Panel and create a new container registry.
  • Follow the instructions to set it up.

• Login to DigitalOcean's registry:
  
  Use the login command provided by DigitalOcean, which will look something like this:
  
  

   doctl registry login

You’ll need the DigitalOcean CLI for this, which can be installed from DigitalOcean CLI documentation.

• Tag your Docker image: Tag your image to match the registry’s URL.

   docker tag myapp registry.digitalocean.com/YOUR_REGISTRY_NAME/myapp:latest

• Push your Docker image to the registry:

   docker push registry.digitalocean.com/YOUR_REGISTRY_NAME/myapp:latest

Step 3: Deploy the Docker Image to DigitalOcean App Platform

• Navigate to the App Platform:
  Go to DigitalOcean's App Platform.

• Create a New App:

  • Click on "Create App".
  • Choose the "DigitalOcean Container Registry" option.

• Select the Docker Image Source:

  • Select the image you pushed earlier.

• Configure the App Settings:

  • Set up scaling options: Configure the number of containers, CPU, and memory settings.
  • Environment variables: Add any environment variables your application might need.
  • Choose the region: Pick a region close to your users for better performance.

• Deploy the App:

  • Click "Next", review the settings, and click "Create Resources".
  • DigitalOcean will take care of provisioning the infrastructure, pulling the Docker image, and starting the application.

Step 4: Monitor and Manage the App

• Access the Application:
  • Once deployed, you will get a public URL to access your application.
  • Test the app to ensure it’s running as expected, e.g.

curl https://myapp.ondigitalocean.app/hello/world

• View Logs and Metrics:

  • Go to the "Runtime Logs" tab in the App Platform to view logs
  • Go to the "Insights" tab to view performance metrics.

• Manage Scaling and Deployment Settings:

  • You can change the app configuration, such as scaling settings, deployment region, or environment variables.

Step 5: Add a Database to Your App

DigitalOcean’s App Platform provides managed databases, allowing you to add a database to your app easily. Here’s how to set up a managed database for your app:

• Navigate to the DigitalOcean Control Panel:

  • Go to DigitalOcean Control Panel.
  • Click on "Databases" in the left-hand sidebar.

• Create a New Database Cluster:

  • Click "Create Database Cluster".
  • Choose PostgreSQL
  • Select the database version, data center region, and cluster configuration (e.g., development or production settings based on your needs).
  • Name the database and configure other settings if necessary, then click "Create Database Cluster".

• Configure the Database Settings:

  • Once the database is created, go to the "Connection Details" tab of the database dashboard.
  • Copy the connection string or individual settings (host, port, username, password, database name). You will need these details to connect your app to the database.
  • Download the CA certificate

• Create a Database

  • Connect to the database using the connection string provided by DigitalOcean.

   psql -h mydb.db.ondigitalocean.com -U doadmin -d mydb -p 25060

• Create a database

    CREATE DATABASE mydb;
    ```


   - Create a table


   ```sql
     CREATE TABLE users (
        id SERIAL PRIMARY KEY,
        name VARCHAR(50)
     );
     INSERT INTO users (name) VALUES ('Alice');

• Declare a Database in your Encore app:
  • Open your Encore app’s codebase.
  • Add mydb database to your app (Encore Database Documentation)

      const mydb = new SQLDatabase("mydb", {
         migrations: "./migrations",
      });

      export const getUser = api(
        { expose: true, method: "GET", path: "/names/:id" },
        async ({id}: {id:number}): Promise<{ id: number; name: string }> => {
          return await mydb.queryRow`SELECT * FROM users WHERE id = ${id}` as { id: number; name: string };
        }
      );

• Create an Encore Infrastructure config
  • Create a file named infra.config.json in the root of your Encore app.
  • Add the CA certificate and the connection details to the file:

   {
      "$schema": "https://encore.dev/schemas/infra.schema.json",
      "sql_servers": [
      {
         "host": "mydb.db.ondigitalocean.com:25060",
         "tls_config": {
            "ca": "-----BEGIN CERTIFICATE-----\n..."
         },
         "databases": {
            "mydb": {
               "username": "doadmin",
               "password": {"$env": "DB_PASSWORD"}
             }
         }
      }]   
   }

• Set Up Environment Variables (Optional):

  • Go to the DigitalOcean App Platform dashboard.
  • Select your app.
  • In the "Settings" section, go to "App-Level Environment Variables"
  • Add the database password as an encrypted environment variable called DB_PASSWORD.

• Build and push the Docker image:

  • Build the Docker image with the updated configuration.

   encore build docker --config infra.config.json myapp

• Tag and push the Docker image to the DigitalOcean container registry.

   docker tag myapp registry.digitalocean.com/YOUR_REGISTRY_NAME/myapp:latest
   docker push registry.digitalocean.com/YOUR_REGISTRY_NAME/myapp:latest

• Test the Database Connection:
  • Redeploy the app on DigitalOcean to apply the changes.
  • Test the database connection by calling the API

    curl https://myapp.ondigitalocean.app/names/1

Troubleshooting Tips

• Deployment Failures: Check the build logs for any errors. Make sure the Docker image is correctly tagged and pushed to the registry.
• App Not Accessible: Verify that the correct port is exposed in the Dockerfile and the App Platform configuration.
• Database Connection Issues: Ensure the database connection details are correct and the database is accessible from the app.

Conclusion

That’s it! You’ve successfully deployed an Encore app to DigitalOcean’s App Platform using Docker.💪

You can now scale your app, monitor its performance, and manage it easily through the DigitalOcean dashboard.

🕹 Try it yourself

• Learn about building apps using Encore with these Tutorials.👈
• Find inspiration on what to build with these Open Source App Templates.👈

Wrapping up

• ⭐️ Support the project by starring Encore on GitHub.
• 💙 If you have questions or want to share your work, join the developers hangout in Encore's community on Discord.