How to Get Started With DigitalOcean’s Serverless Functions

Functions is one of the newest additions to the DigitalOcean cloud platform. It provides a first-class method for developing serverless functions without leaving DigitalOcean. Your code’s executed on-demand when it’s called, eliminating manual server provisioning and maintenance.

In this article we’ll explain what DigitalOcean Functions supports and walkthrough a demonstration of creating your own simple function. Functions has a free tier that provides 25 GiB-hours per month, with a GiB-second calculated as the memory consumption multiplied by the execution time of each function call.

Supported Features

Launched in May 2022, Functions gives DigitalOcean customers a built-in option for running serverless workloads. Each function gets its own API endpoint that runs the code you’ve created. You don’t have to set up your own servers or containerize the project before deployment. Live functions are hosted by DigitalOcean’s App Platform backend.

Functions can integrate with DigitalOcean’s Managed Databases to facilitate persistent data storage. They also come with a comprehensive CLI that lets you deploy and test your code in your terminal.

The initial version of the platform supports five different programming environments:

• Go 1.17
• Node.js 14
• Node.js 14 (compatible with AWS Lambda functions)
• PHP 8
• Python 3.9

You’ll need to be comfortable writing your code in one of these languages to deploy it as a function. More runtimes could be supported in the future.

Getting Set Up

It’s possible to launch new functions using DigitalOcean’s web control panel or Doctl, its developer-oriented CLI. We’re focusing on the terminal-based Doctl approach for the purposes of this article. This exposes all the capabilities of Functions and is the intended pathway for all but the simplest use cases. Make sure you’ve got the latest version of Doctl installed and authenticated to your DigitalOcean account before you continue.

You’ll need to complete some further set up steps if this is the first time you’re using DigitalOcean Functions. First finish the installation of Doctl’s serverless extension. This adds full support for developing and deploying functions.

$ doctl serverless install
Downloading...Unpacking...Installing...Cleaning up...
Done

Next connect the serverless features to your DigitalOcean account:

$ doctl serverless connect
Connected to function namespace 'fn-3c1d9001-8e04-44e8-9375-c22b13c4a41a' on API host 'https://faas-lon1-917a94a7.doserverless.co'

Now you should be ready to start writing functions. Run the serverless status command to check everything’s working:

$ doctl serverless status
Connected to function namespace 'fn-3c1d9001-8e04-44e8-9375-c22b13c4a41a' on API host 'https://faas-lon1-917a94a7.doserverless.co'
Sandbox version is 3.1.1-1.2.1

The output shown above confirms Functions support is installed and ready to use.

The serverless command is an alias of sandbox. At the time of writing, the two keywords have identical functionality and are used interchangeably across DigitalOcean’s documentation. We’re standardizing on serverless for this guide.

Creating a Function

Use the following command to create a new Functions project:

$ doctl serverless init --language js demo-project
A local sandbox area 'demo-project' was created for you.
You may deploy it by running the command shown on the next line:
  doctl sandbox deploy demo-project

This command creates a new JavaScript function within demo-project in your working directory. Inspect the contents of this directory to see what Doctl has scaffolded for you:

$ tree demo-project
demo-project
├── packages
│   └── sample
│       └── hello
│           └── hello.js
└── project.yml

3 directories, 2 files

The project.yml file is where you configure your functions project and the endpoints it provides.

targetNamespace: ''
parameters: {}
packages:
  - name: sample
    environment: {}
    parameters: {}
    annotations: {}
    actions:
      - name: hello
        binary: false
        main: ''
        runtime: 'nodejs:default'
        web: true
        parameters: {}
        environment: {}
        annotations: {}
        limits: {}

The starter template configures one package called sample. Within this package, there’s a single action (endpoint) named hello that’s executed using the Node runtime. The source code for this action is stored at packages/sample/hello/hello.js. Let’s look at this file next:

function main(args) {
    let name = args.name || 'stranger'
    let greeting = 'Hello ' + name + '!'
    console.log(greeting)
    return {"body": greeting}
}

This is regular JavaScript code. The main() function will be invoked each time your function’s called. It receives an object containing arguments submitted as HTTP GET and POST data in the user’s request. You can configure static arguments too, using the parameters field on actions, packages, and the top-level project in your project.yml file.

Functions need to return an object that describes the HTTP response to issue. The body field becomes the data included in the response.

Invoking and Deploying Functions

This project is ready to run. Use this command to deploy your function:

$ doctl serverless deploy .
Deploying '/home/james/@scratch/demo-project'
  to namespace 'fn-3c1d9001-8e04-44e8-9375-c22b13c4a41a'
  on host 'https://faas-lon1-917a94a7.doserverless.co'
Deployment status recorded in '.nimbella'

Deployed functions ('doctl sbx fn get <funcName> --url' for URL):
  - sample/hello

The serverless deploy command takes one argument, the path to the directory that contains your functions. Use . when the root of your project is already your working directory.

Now you can test your function using the CLI:

$ doctl serverless functions invoke sample/hello -p name:howtogeek
{
    "body": "Hello howtogeek!"
}

The -p parameter sets an argument that’s passed through to your code. This example demonstrates how your function’s return value becomes the HTTP response body.

Next try making a real API request to your function. You can discover its URL with the following command:

$ URL=$(doctl serverless functions get sample/hello --url)

Use curl or your own favorite HTTP client to hit this endpoint:

$ curl $URL?name=howtogeek
Hello howtogeek!

The name query string parameter has been successfully passed through to the function.

Modifying Your Function

So far we’re using DigitalOcean’s sample code without any modification. This isn’t going to take you far on your serverless journey! Edit your hello.js file so it looks like this:

function main(args) {
    return {
        body: {
            value: (args.value * 2),
            timestamp: Date.now()
        },
        headers: {
            "Content-Type": "application/json"
        }
    };
}

Re-deploy your function:

$ doctl serverless deploy .

This function naively doubles the number given by the value request parameter. It also includes a timestamp with each response body. The headers field is used in the response object to apply a correct JSON Content-Type.

You can call this function using Doctl or curl in the same style as earlier:

$ curl $URL?value=2
{
  "timestamp": 1654784122966,
  "value": 4
}

Manually re-deploying your function after each change is tedious and time-consuming. Run the watch command while you work to automatically deploy changes after you modify your files:

$ doctl serverless watch .
Watching '.' [use Control-C to terminate]

Keep the terminal window open as you develop your function. Each new deployment will log a message so you know when you can test your changes. This facilitates efficient iteration as you develop your functions.

You can stream logs from your functions too. This is invaluable when a function crashes or doesn’t behave as you expected. Run this command to access the logs associated with your demo function:

$ doctl serverless activations logs --follow --function sample/hello

A new line will be printed each time you call your function. The logs also include messages that your code emits to the environment’s standard output and error streams.

Deploying to Production

The serverless deploy command is currently designed for development use only. You can deploy to production by creating a Git repository for your Functions project and launching it using DigitalOcean’s App Platform.

Create a new project on GitHub or GitLab and push up your code:

$ git init
$ git remote add origin git@github.com:user/repo.git
$ git add .
$ git commit -m "initial commit"
$ git push -u origin master

Next head to your DigitalOcean control panel and click the “Apps” link in the left sidebar. Click the “Create App” button that appears. On the next screen, follow the prompts to connect to your GitHub account and select your new repository. Press the blue “Next” button.

DigitalOcean will automatically detect your repository as a Functions project if you’ve got a project.yml at its root. Click the “Skip to Review” button to continue.

The next screen should confirm you’ll be billed using the Functions plan.

Press “Create Resources” to provision your app and start its first deployment. Progress will be shown on the dashboard.

Your function’s endpoints will be publicly accessible once the deployment completes. You can find your app’s default ondigitalocean.app domain by scrolling down the App Settings page in your dashboard. In our example, the app’s domain is sea-lion-app.7ougx.ondigitalocean.app.

Functions are automatically exposed as URIs that have the following format:

<app>.ondigitalocean.app/<function-package>/<function-action>

You can invoke the sample function created earlier by making the following request:

$ curl https://sea-lion-app.7ougx.ondigitalocean.app/sample/hello?value=2
{
  "timestamp": 1654786505969,
  "value": 4
}

The function’s been successfully deployed! You can now use the Domains tab in your app’s settings to attach a custom domain instead of the default one.

Summary

DigitalOcean Functions is the newest competitor in the increasingly crowded serverless functions arena. The platform lets you develop server-side functionality without managing VMs or manually containerizing your code.

Functions provides a comprehensive CLI for building and testing your endpoints. You can then deploy your functions to DigitalOcean’s existing App Platform solution, either as a standalone project or as part of a larger app.

Once you’ve got a basic function operational, you can refer to DigitalOcean’s documentation to start configuring more advanced behaviors. You can set up environment variables, multiple actions, and resource limits using the fields in your project.yml file, giving you a quick and easy route to build relatively complex on-demand endpoints.