How to Manage Services in App Platform

App Platform is a Platform-as-a-Service (PaaS) offering that allows developers to publish code directly to DigitalOcean servers without worrying about the underlying infrastructure.


The usual app creation process will create a service by default; you only need to follow this process if you’re creating another resource for your app that needs an internet-accessible endpoint. If your resource only needs to be internally accessible, create a internal service instead. If you don’t need this resource to be internet-accessible, create a worker instead.

Add a Service to an App Using Automation

You can add a service to an app using the CLI’s app update command or the API’s app update endpoint. To add a service, update the app’s spec with the service’s specifications and submit the spec using the following command or endpoint.

How to add a service to an app using the DigitalOcean CLI

To add a service to an app via the command-line, follow these steps:

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token, and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

                  doctl auth init
                
  4. Finally, add a service to an app with doctl apps update. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl apps update <app id> [flags]
                

    The following example updates an app with the ID f81d4fae-7dec-11d0-a765-00a0c91e6bf6 using an app spec located in a directory called /src/your-app.yaml. Additionally, the command returns the updated app’s ID, ingress information, and creation date

                       doctl apps update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --spec src/your-app.yaml --format ID,DefaultIngress,Created
                    
How to add a service to an app using the DigitalOcean API

To add a service to an app using the DigitalOcean API, follow these steps:

  1. Create a personal access token, and save it for use with the API.

  2. Send a PUT request to https://api.digitalocean.com/v2/apps/{id}

    cURL

    To add a service to an app with cURL, call:

    
                    curl -X PUT \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
      "https://api.digitalocean.com/v2/apps/{id}"

    Python

    
                    import os
    from pydo import Client
    
    client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
    req = {
    "spec": {
        "name": "web-app-01",
        "region": "nyc",
        "domains": [
            {
                "domain": "app.example.com",
                "type": "DEFAULT",
                "wildcard": True,
                "zone": "example.com",
                "minimum_tls_version": "1.3",
            }
        ],
        "services": [],
        "static_sites": [
            {
                "cors": {
                    "allow_origins": [
                        {"exact": "https://www.example.com"},
                        {"regex": "^.*example.com"},
                    ],
                    "allow_methods": [
                        "GET",
                        "OPTIONS",
                        "POST",
                        "PUT",
                        "PATCH",
                        "DELETE",
                    ],
                    "allow_headers": ["Content-Type", "X-Custom-Header"],
                    "expose_headers": ["Content-Encoding", "X-Custom-Header"],
                    "max_age": "5h30m",
                    "allow_credentials": False,
                },
                "routes": [{"path": "/api", "preserve_path_prefix": True}],
            }
        ],
        "jobs": [
            {
                "name": "api",
                "gitlab": {
                    "branch": "main",
                    "deploy_on_push": True,
                    "repo": "digitalocean/sample-golang",
                },
                "image": {
                    "registry": "registry.hub.docker.com",
                    "registry_type": "DOCR",
                    "repository": "origin/master",
                    "tag": "latest",
                },
                "dockerfile_path": "path/to/Dockerfile",
                "build_command": "npm run build",
                "run_command": "bin/api",
                "source_dir": "path/to/dir",
                "envs": [
                    {
                        "key": "BASE_URL",
                        "scope": "BUILD_TIME",
                        "type": "GENERAL",
                        "value": "http://example.com",
                    }
                ],
                "environment_slug": "node-js",
                "log_destinations": {
                    "name": "my_log_destination",
                    "papertrail": {
                        "endpoint": "https://mypapertrailendpoint.com"
                    },
                    "datadog": {
                        "endpoint": "https://mydatadogendpoint.com",
                        "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                    },
                    "logtail": {
                        "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                    },
                },
                "instance_count": 2,
                "instance_size_slug": "apps-s-1vcpu-0.5gb",
                "kind": "PRE_DEPLOY",
            }
        ],
        "workers": [
            {
                "name": "api",
                "gitlab": {
                    "branch": "main",
                    "deploy_on_push": True,
                    "repo": "digitalocean/sample-golang",
                },
                "image": {
                    "registry": "registry.hub.docker.com",
                    "registry_type": "DOCR",
                    "repository": "origin/master",
                    "tag": "latest",
                },
                "dockerfile_path": "path/to/Dockerfile",
                "build_command": "npm run build",
                "run_command": "bin/api",
                "source_dir": "path/to/dir",
                "envs": [
                    {
                        "key": "BASE_URL",
                        "scope": "BUILD_TIME",
                        "type": "GENERAL",
                        "value": "http://example.com",
                    }
                ],
                "environment_slug": "node-js",
                "log_destinations": {
                    "name": "my_log_destination",
                    "papertrail": {
                        "endpoint": "https://mypapertrailendpoint.com"
                    },
                    "datadog": {
                        "endpoint": "https://mydatadogendpoint.com",
                        "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                    },
                    "logtail": {
                        "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                    },
                },
                "instance_count": 2,
                "instance_size_slug": "apps-s-1vcpu-0.5gb",
            }
        ],
        "functions": [
            {
                "cors": {
                    "allow_origins": [
                        {"exact": "https://www.example.com"},
                        {"regex": "^.*example.com"},
                    ],
                    "allow_methods": [
                        "GET",
                        "OPTIONS",
                        "POST",
                        "PUT",
                        "PATCH",
                        "DELETE",
                    ],
                    "allow_headers": ["Content-Type", "X-Custom-Header"],
                    "expose_headers": ["Content-Encoding", "X-Custom-Header"],
                    "max_age": "5h30m",
                    "allow_credentials": False,
                },
                "routes": [{"path": "/api", "preserve_path_prefix": True}],
                "name": "api",
                "source_dir": "path/to/dir",
                "alerts": [
                    {
                        "rule": "CPU_UTILIZATION",
                        "disabled": False,
                        "operator": "GREATER_THAN",
                        "value": 2.32,
                        "window": "FIVE_MINUTES",
                    }
                ],
                "envs": [
                    {
                        "key": "BASE_URL",
                        "scope": "BUILD_TIME",
                        "type": "GENERAL",
                        "value": "http://example.com",
                    }
                ],
                "gitlab": {
                    "branch": "main",
                    "deploy_on_push": True,
                    "repo": "digitalocean/sample-golang",
                },
                "log_destinations": {
                    "name": "my_log_destination",
                    "papertrail": {
                        "endpoint": "https://mypapertrailendpoint.com"
                    },
                    "datadog": {
                        "endpoint": "https://mydatadogendpoint.com",
                        "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                    },
                    "logtail": {
                        "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                    },
                },
            }
        ],
        "databases": [
            {
                "cluster_name": "cluster_name",
                "db_name": "my_db",
                "db_user": "superuser",
                "engine": "PG",
                "name": "prod-db",
                "production": True,
                "version": "12",
            }
        ],
    }
    }
    update_resp = client.apps.update(id="bb245ba", body=req)

Add a Service to an App Using the Control Panel

  1. In the Apps section of the DigitalOcean Control Panel, select your app, then click the Create dropdown and choose Create Resources From Source Code to add a Web Service.
Resources screen
  1. Select the repository service to retrieve your source code from, either: GitHub, GitLab, DigitalOcean Container Registry, Docker Hub, or a sample app. If you are connecting to your repository from DigitalOcean for the first time, you will need to click the Manage Access button to provide DigitalOcean access to the repositories or containers, then refresh this page.

  2. Select the repository from the Repository drop-down list. Next, select which branch of the source repo you’d like to use as the source. Optionally, for monorepos, specify the folder that contains the source in the Source Directory field. For containers, specify the image tag to use. Click Next.

    App Platform will inspect the code, select an appropriate resource type and also detect any appropriate build and run commands.

Create web service

To change to a different resource type, click the edit icon to open the Settings page of the resource. Click Edit next to Resource Type, choose another option from the Type drop-down list. Click Save to confirm your changes.

In the settings page, you can also change the resource’s name, view the resource’s buildpacks, edit its build and run commands, edit the HTTP port and the request route, and more. Click Save to confirm your changes.

Create web service settings
  1. Optionally, if you want to specify additional resources, click the Add Additional Resource From Source link, repeat the procedure and click Next.

  2. If you need to use environment variables, click Edit to the right of the resource name and supply them. Click the Encrypt checkbox to ensure a variable’s value is obscured in all build, deploy, and application logs.

    To specify an app-level environment variable, click Edit to the right of Global. Click Save and then click Next.

    See How to Use Environment Variables in App Platform for more details.

    Resources env variables
  3. Review the resources, environment variables and pricing, and click Create Resources.

Note
The service must bind to and expose the HTTP port on the network interface 0.0.0.0 , rather than on the localhost (localhost) or loopback interface (127.0.0.1).

Full HTTP request path preservation for services is not available in the control panel. Instead, set the preserve_path_prefix annotation in the App Spec to true.

Edit a Service

In the Apps section of the DigitalOcean Control Panel, select your app and click on the Settings tab. Click the Web Service you’d like to edit.

You can use the configuration settings you see here to change the Web Service’s scaling behavior, modify environment variables, edit commands, and more.

Destroy a Service

In the Apps section of the DigitalOcean Control Panel, select your app and click on the Settings tab. Click on the Web Service you’d like to destroy.

You can destroy the Web Service by clicking the Destroy Component button on the bottom of the page and entering its name to confirm your selection.

Create an Internal Service

Internal services are not available for creation via the control panel, they need to be created within the App spec. Documentation to deploy via doctl.

Adding another service to your app spec, like so:

services:
- environment_slug: go
  github:
    branch: master
    deploy_on_push: true
    repo: digitalocean/sample-golang
  instance_count: 1
  instance_size_slug: basic-xxs
  internal_ports:
  - 8080
  name: internal-service
  run_command: bin/sample-golang

This service has no HTTP port and route, making it inaccessible from the outside world. However, port 8080 is exposed internally making it an internal service. This service can be reached by workers and other services using the resource name and the port, which in this example would be http://internal-service:8080. Services that are publicly accessible can function as an internal service as well by defining internal ports.

Add a Function

To add Functions, adjust your app spec like so:

name: go-random
region: nyc
functions:
- name: go-api
  github:
    repo: digitalocean/sample-functions-golang-random
    branch: master
    deploy_on_push: true

This process requires you to authorize to GitHub and specify the region you want to create the Function in. You can also delete the region field to automatically create the Function in the datacenter closest to you.