Skip to main content

Getting started with subhosting

To get started with subhosting, you will need to create an organization in the Deno Deploy dashboard. Follow the on-screen instructions to create a new organization for subhosting.

Going through the onboarding flow, you will likely also generate an access token, which you will use to access the REST API. If you didn't do this (or lost the token you generated), you can generate a new one here.

Save your token in a safe place

Once you generate an access token, it will not be displayed again within the Deploy dashboard UI. Make sure you store this token in a safe place.

Set up a test environment​

In the tutorial pages to follow, we will assume you are interacting with the Deploy REST API through Deno scripts (TypeScript code), and will show examples of interacting with the API in this way. However, the techniques shown here will also work in any other environment capable of executing HTTP requests.

The example code shown here and in future chapters assume that you have Deno 1.38 or higher installed.

When working with a REST API, it is useful to store authentication credentials in the system environment, to prevent you from accidentally checking them in to source control.

For this tutorial, we'll use the new --env flag introduced in Deno 1.38 to manage environment variables. On your local computer, create a new directory to store our management scripts in, and create three files:

  • .env - to hold our API access info
  • .gitignore - to ignore our .env file so we don't put it in source control by mistake
  • create_project.ts - a file we'll use in a moment to make our first request to the REST API

Configure a .env file and .gitignore file​

First, store your access token and organization ID in the .env file you created earlier.

.env
DEPLOY_ACCESS_TOKEN=your_token_here
DEPLOY_ORG_ID=your_org_id_here

Replace the values in the file with the values from your own Deploy account.

Next, create a .gitignore file just to ensure we don't accidentally check our .env file into source control:

.gitignore
# Ignore this file in git
.env

# Optional: ignore this junk file often generated on mac OS
.DS_Store

Now that we have our credentials set up, let's write some code to access the REST API.

Creating our first project​

In order to do anything interesting with subhosting or the REST API, we'll need to create a project. Copy the code below into a file named create_project.ts in the same file as your .env and .gitignore file.

create_project.ts
const accessToken = Deno.env.get("DEPLOY_ACCESS_TOKEN");
const orgId = Deno.env.get("DEPLOY_ORG_ID");
const API = "https://api.deno.com/v1";

// Create a new project
const res = await fetch(`${API}/organizations/${orgId}/projects`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: null, // randomly generates project name
  }),
});

const project = await res.json();
console.log(project);

Execute this code with the following command in a terminal:

deno run -A --env create_project.ts

If everything goes according to plan, you should see output that looks something like this:

{
  id: "f084712a-b23b-4aba-accc-3c2de0bfa26a",
  name: "strong-fox-44",
  createdAt: "2023-11-07T01:01:14.078730Z",
  updatedAt: "2023-11-07T01:01:14.078730Z"
}

Note the id of the project that was returned with this repsonse - this is the project ID we'll use in the next step.

Now that we have REST API access configured and a project set up, we can move on to creating our first deployment.