Quick Start
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, you can run 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 both Golang and Rust as the Guest Languages, but compiling them requires the appropriate toolchain to be installed on your machine.
To streamline compiling Scale Functions in the future, we’re working on a cloud build service that will allow you to
compile your functions without having to install the toolchain on your machine. If you’re interested in accessing this
service as soon as it’s available, please join the #scale on our discord.
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.
Golang
Rust
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:
scale new hello-world
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 new hello-world -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 new hello-world -l rust
The following files will be created in the directory depending on the language you chose:
Golang
Rust
version: v1alpha
name: hello-world
tag: latest
signature: http@v0.3.4
language: go
dependencies:
- name: github.com/loopholelabs/scale-signature
version: v0.2.9
- name: github.com/loopholelabs/scale-signature-http
version: v0.3.4
source: scale.go
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 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 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 run or scale 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-world latest 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 run hello-world:latest
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 run hello-world:latest -l :3000
The scale 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 push hello-world:latest
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 push hello-world:latest --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 pull <your organization>/hello-world:latest
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 pull <your organization>/hello-world:latest --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.