Quick Start
Create, run, and publish your first Scale Function in minutes.
In this section we’ll be going over how you can quickly get started with Scale to create, run and even publish your own function.
We’ll be building a simple Hello World function using the HTTP Signature that will return a simple greeting.
Install the Scale CLI
The Scale CLI is the primary tool for interacting with Scale Functions and the Scale Registry. It can be easily installed using the following command:
curl -fsSL https://dl.scale.sh | sh
The CLI attempts to install itself to /usr/local/bin by default, but you can also specify a different directory by setting the INSTALL environment variable like so:
curl -fsSL https://dl.scale.sh | INSTALL=./ sh
To verify that the CLI was installed correctly, check the scale cli version by running the following command:
scale version
For alternative installation methods or to build the CLI from source, please see the CLI Installation Guide.
Install the Toolchain for your Guest Language
Scale Functions currently support using Golang, TypeScript/JavaScript, and Rust as the Guest Languages, but compiling them requires the appropriate toolchain to be installed on your machine.
If you already have the toolchain for your Guest Language installed, you can skip this step. Otherwise, you can follow the guides for your Guest Language below to install the toolchain.
Installing the Golang Toolchain
To use Golang as the Guest Language, you'll need to install the following:
The best way to install Go is to follow the official instructions for your operating system and platform at https://go.dev/doc/install.
You can verify that Go was installed correctly by running the following command:
go version
The minimum supported version of Go for use with Scale Functions is 1.18.
The best way to install TinyGo is to follow the official instructions for your operating system and platform at https://tinygo.org/getting-started/install/.
You can verify that TinyGo was installed correctly by running the following command:
tinygo version
The minimum supported version of TinyGo for use with Scale Functions is 0.27.0.
Create a New Function
Once you have the Scale CLI and the toolchain for your Guest Language installed, you can create a new function by
running the following command, passing a <name>:<tag> pair to the new command:
scale fn new hello:1.0
This will create a new scale function in the current directory. You can also specify a different directory by passing the
--directory or -d flag:
scale fn new hello:1.0 -d /path/to/directory
By default, the CLI will create a new function using Golang as the Guest Language. If you want to use Rust instead,
you can pass the --language or -l flag:
scale fn new hello:1.0 -l rust
The following files will be created in the directory depending on the language you chose:
The scalefile is the main configuration file for the function. It contains all of the metadata and configuration required
to build and run the function. The scale.go file contains the actual implementation of the function, and
the go.mod file is primarily used to provide Intellisense
and Auto-Completion support in your IDE.
You’ll notice that at the end of the Scale Function we call the Next() function. This is because Scale Functions can be
chained together to form a pipeline. The Next() function is used to pass the context to the next function in the chain
and can be conditionally called based on the logic in your function.
This allows for powerful composability that’s completely language agnostic. For example, you can use a rust function to validate the request, a golang function to process the request, and a third rust function to generate the response!
If you call the Next() field and there is no next function in the chain, the function is a no-op and the context is returned.
When adding new dependencies to your function, you’ll need to add references to them in the scalefile to make sure
your function can be built properly.
By default, the generated function will be configured to use the HTTP Signature,
which provides an interface for handling HTTP requests and responses. To learn more about the HTTP Signature and the
interfaces it provides, you can check out the HTTP Signature Reference.
The concept of a Signature is central to how Scale Functions provide cross-language type safety and it’s documented
in more detail in the Signatures section of the documentation.
Build the Function
Once you’ve created a new function, you can build it by running the following command:
scale function build
This will build the function and save it to the Cache Directory (which defaults to ~/.config/scale/functions on Linux and macOS).
You can also specify a different directory by passing the --cache-directory flag:
scale function build --cache-directory /path/to/directory
The Cache Directory is where the Scale CLI stores all of the built functions. This is where the CLI will look for
functions when you run commands like scale fn run or scale fn push.
To list all of the functions that are currently in the Cache Directory, you can run the following command:
scale function list
NAME (1) TAG ORG LANGUAGE SIGNATURE HASH VERSION
------------------- -------- ------------- ---------- ------------- ------------------------------------------------------------------ ---------
hello 1.0 local rust http@v0.3.4 8dad03b701cd124b55ff5caf7a36a9af5d19759fc73a9e8299bea4816f929777 v1alpha
Run the Function
Once you’ve built the function, you can run it by running the following command:
scale fn run local/hello:1.0
This will start a local HTTP server on port 8080 and will run the function whenever you make a request to it. You can
also specify a different port by passing the --listen or -l flag:
scale fn run local/hello:1.0 -l :3000
The scale fn run command is designed for use with the HTTP Signature. It can be used for both
local development and production deployments and makes it easy to test your function without having to deploy it.
Push the Function
Now that you’ve built and tested your function, you can push it to the Scale Registry. Once pushed, the function can be pulled and used in your existing Typescript or Golang services, or even by other users for their own applications.
Using the Scale Registry is completely free during our beta period. To learn more about our future plans for the Scale Registry,
please join the #scale channel on our Discord.
To use the Scale Registry, you’ll first have to authenticate with the Scale API. This process is the same for both new and existing users.
If you are a new user you can still follow along with this guide. Your account will be created automatically when you first sign in.
To authenticate with the Scale API, you can run the following command:
scale auth login
This will open a browser window and prompt you to log in to your Scale account. Once you’ve logged in, you can close the browser window and return to the terminal. You should now be able to push your function to the Scale Registry.
To check that you’re authenticated, you can run the following command:
scale auth status
MEMBER ORGS OWNED ORGS EMAIL ORG
------------- --------------- ----------------------------- -------------
[] [shivanshvij] shivanshvij@loopholelabs.io shivanshvij
It’s also possible to authenticate with the Scale API using an API Key. To learn more about API Keys, you can check out the API Keys section of the documentation.
Once you’ve authenticated with the Scale API, you can push your function to the Scale Registry by running the following command:
scale function push hello:1.0
This will push the function to the Scale Registry and make it available for use in your existing services. By default
the function will be private, but you can make it public by passing the --public flag:
scale function push hello:1.0 --public
The Scale Registry is currently in beta and may be subject to changes in the future. To learn more about the
Scale Registry, you can check out the Registry section of the documentation or join the #scale
channel in our Discord.
Pulling a Function
Once you’ve pushed a function to the Scale Registry, you can pull it and use it in your existing services. To pull a function, you can run the following command:
scale function pull <your organization>/hello:1.0
When you pushed the function to the Scale Registry, it was pushed to a specific organization.
You can find the name of the organization by running the scale auth status command.
If you pushed the function using the --public flag, you can pull it without being authenticated with the Scale API.
This will pull the function from the Scale Registry and save it to the Cache Directory (which defaults to ~/.config/scale/functions on Linux and macOS).
You can also specify a different directory by passing the --cache-directory flag:
scale function pull <your organization>/hello:1.0 --cache-directory /path/to/directory
The scale pull command only pulls the contents of the scale function from the registry if it’s not already present.
If the function is already present, it will not be overwritten unless the --force flag is passed.
Next Steps
Now that you’ve created and pushed your first function, you can check out the Importing Scale Functions guide for Golang and Typescript/Javascript to learn how to use your function inside your existing services (and to chain them alongside native functions).
You can also check out our Adapter Guides to learn how to integrate your functions with popular frameworks such as Next.js.
To learn more about how the Scale Registry works, you can check out the Registry section, or you can check out the Signatures section to learn more about how Scale Signatures work.