# Deploying with the Serverless Toolkit

> \[!NOTE]
>
> This means this project is 100% open-source. You can find its source code in the [Twilio Labs GitHub organization](https://github.com/twilio-labs).
>
> We currently don't support the projects through our official support channels. But you are welcome to reach out to us on GitHub for any questions, issues or suggestions or to contribute to this project.
>
> [Learn more about Twilio Labs](/docs/labs).

There are two ways you can use the [toolkit](/docs/labs/serverless-toolkit). If you are already using the Twilio CLI, you can install it via a plugin. Alternatively, you can use the toolkit as a standalone using twilio-run via npm or another Node.js package manager.

Throughout the docs we'll reference the Twilio CLI commands.

> \[!NOTE]
>
> The Serverless Toolkit will perform a collection of API requests on your behalf and in order to speed things up might do so in parallel. Depending on your account it might get into the situation where you hit issues deploying due to concurrency issues.
>
> To solve this issue, you can [set the environment variable](https://www.twilio.com/blog/how-to-set-environment-variables-html) `TWILIO_SERVERLESS_API_CONCURRENCY` to a value such as 1 to avoid any requests being performed in parallel.

## Deploying new code

The Serverless Toolkit tries to make deploying as seamless and with as little configuration as possible. If you have a project set-up according to the [Serverless project structure](/docs/labs/serverless-toolkit/general-usage#project-structure), all it takes to deploy is one short command.

```bash title="Deploy a Twilio Serverless project"
# Run a basic deployment with default settings
twilio serverless:deploy
```

By default this will create a new environment for you with the following properties:

* Domain Suffix: *dev*
* Unique Name: *dev-environment*

You can change the environment it deploys to by passing the domain suffix of the environment into the *deploy command* using the `--environment` flag. If an environment with that domain suffix already exists, it will deploy to that one, otherwise it will create a new one.

```bash title="Deploy a Serverless project to a staging environment"
twilio serverless:deploy --environment=staging
```

If you don't pass any other options in, the Functions and Assets that are being deployed will be chosen based on your project structure. If you use a non-default folder name for the deployment of Assets or Functions, you can pass in the `--assets-folder` or `--functions-folder` flags to change them. Alternatively you can use the `--no-assets` and `--no-functions` flags to turn these features of completely.

```bash title="Deploy a Serverless project without assets"
twilio serverless:deploy --no-assets
```

Additionally any variables except `ACCOUNT_SID` and `AUTH_TOKEN` will be uploaded as part of your deployment. To change the variables that are being uploaded use the `--env` flag to point against another *.env file*.

```bash title="Deploy a Serverless project with different variables"
twilio serverless:deploy --env .env.prod
```

There's a lot more configuration you can do for your deployment. The best way you can find out about the various options is using the `--help` flag. It will list all options you have available.

## Regional deployments

When deploying Functions and Assets to a specific [Twilio Region](/docs/global-infrastructure/understanding-twilio-regions), you need to ensure your deployment uses the correct regional credentials and endpoints.

### Method 1: Using CLI profiles (recommended)

The recommended approach is to create a regional [CLI profile](/docs/twilio-cli/general-usage/profiles) with both region and edge specified:

```bash
# Create a regional profile
twilio login --region au1 --edge sydney

# Set it as active
twilio profiles:use australia-prod

# Deploy using the regional profile
twilio serverless:deploy
```

All deployments will automatically use the region and edge configured in the active profile.

### Method 2: Using environment variables

You can also specify region and edge using environment variables:

```bash
export TWILIO_ACCOUNT_SID=ACxxxx
export TWILIO_API_KEY=SKxxxx
export TWILIO_API_SECRET=your-secret
export TWILIO_REGION=ie1
export TWILIO_EDGE=dublin

twilio serverless:deploy
```

> \[!NOTE]
>
> Environment variables take precedence over profile settings. If both are set, the environment variables will be used.

### Method 3: Using configuration file

You can specify region and edge in your `.twilioserverlessrc` configuration file:

**Top-level configuration (applies to all environments):**

```json
{
  "region": "jp1",
  "edge": "tokyo",
  "serviceName": "my-service",
  "functionsEnv": ".env"
}
```

**Environment-scoped configuration:**

```json
{
  "serviceName": "my-service",
  "environments": {
    "production": {
      "region": "au1",
      "edge": "sydney",
      "functionsEnv": ".env.production"
    },
    "staging": {
      "region": "ie1",
      "edge": "dublin",
      "functionsEnv": ".env.staging"
    }
  }
}
```

### Important: Regional credentials required

When deploying to a non-US1 region, ensure you're using credentials that were created in that specific region. Each region has its own Auth Tokens and API Keys.

> \[!WARNING]
>
> Valid region and edge combinations for serverless deployments:
>
> * `region: "au1"`, `edge: "sydney"` (Australia)
> * `region: "ie1"`, `edge: "dublin"` (Ireland)
> * `region: "jp1"`, `edge: "tokyo"` (Japan)
>
> If you specify a region, you must also specify the corresponding edge location.

For more information:

* [Understanding Twilio Regions](/docs/global-infrastructure/understanding-twilio-regions)
* [Understanding Edge Locations](/docs/global-infrastructure/understanding-edge-locations)
* [Regional Functions and Assets](/docs/global-infrastructure/regional-support-functions-assets)

## Replicating an existing deployment

Aside of deploying code to an environment by uploading everything again, you can take an existing deployment and activate it on another environment using the *promote command.* For example to move the same build from the *dev* environment to an environment with the domain suffix *staging* you can use the activate command.

```bash title="Promote a build from one environment to another [serverless]"
twilio serverless:promote --source-environment=dev --environment=stage
```

## What's next?

Now that you learned how you can deploy your Twilio Functions, why not learn more, like how you can locally develop and debug your Functions.

* [Getting Started](/docs/labs/serverless-toolkit/getting-started)
  * [Install the toolkit](/docs/labs/serverless-toolkit/getting-started#install-the-twilio-serverless-toolkit)
  * [Explore available commands](/docs/labs/serverless-toolkit/getting-started#explore-the-commands-and-options)
* [General Usage](/docs/labs/serverless-toolkit/general-usage)
  * [Create a project](/docs/labs/serverless-toolkit/general-usage#create-a-project)
  * [Project structure](/docs/labs/serverless-toolkit/general-usage#project-structure)
  * [Start developing locally](/docs/labs/serverless-toolkit/general-usage#start-developing-locally)
  * [Create a new Twilio Function](/docs/labs/serverless-toolkit/general-usage#create-a-new-twilio-function)
  * [Deploy a project](/docs/labs/serverless-toolkit/general-usage#deploy-a-project)
* [Developing and Debugging](/docs/labs/serverless-toolkit/developing)
* [Examples](/docs/labs/serverless-toolkit/examples)
* Guides
  * [Using Twilio Serverless with TypeScript](/docs/labs/serverless-toolkit/guides/typescript)