Skip to content

Commit

Permalink
Improve Deno Deploy quickstart
Browse files Browse the repository at this point in the history
  • Loading branch information
@ry
ry committed Nov 2, 2023
1 parent e0c1c8f commit 5fb3eca
Show file tree
Hide file tree
Showing 2 changed files with 146 additions and 144 deletions.
114 changes: 106 additions & 8 deletions deploy/manual/deployctl.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,115 @@
# Using deployctl on the command line

`deployctl` is a command line tool (CLI) that lets you work with the Deno Deploy
platform.
[`deployctl`](https://github.com/denoland/deployctl) is a command line tool
(CLI) that lets you work with the Deno Deploy platform.

## Install `deployctl`
## Getting started

You can install the `deployctl` command with the below command:
If you haven't already, you can
[install the Deno runtime](/runtime/manual/getting_started/installation) using
one of the commands below:

deno install --allow-all --no-check -r -f https://deno.land/x/deploy/deployctl.ts
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

You also need to set the `DENO_DEPLOY_TOKEN` environment variable to your
personal access token. You can generate your Personal Access Token in
https://dash.deno.com/account#access-tokens.
<Tabs groupId="operating-systems">
<TabItem value="mac" label="macOS" default>

```sh
curl -fsSL https://deno.land/x/install/install.sh | sh
```

</TabItem>
<TabItem value="windows" label="Windows">

```powershell
irm https://deno.land/install.ps1 | iex
```

</TabItem>
<TabItem value="linux" label="Linux">

```sh
curl -fsSL https://deno.land/x/install/install.sh | sh
```

</TabItem>
</Tabs>

After Deno is installed, install the [`deployctl`](./deployctl.md) utility:

```
deno install -A --no-check -r -f https://deno.land/x/deploy/deployctl.ts
```

You can confirm `deployctl` has been installed correctly by running:

```
deployctl --help
```

Now, you're ready to deploy a Deno script from the command line!

### Sign up for Deno Deploy and create a blank project

If you haven't already, now is the time to
[sign up for a Deno Deploy account](https://dash.deno.com). After signing up,
[click the "New Project" button here](https://dash.deno.com). Near the top of
the page, you'll see an option to "create a blank project" - choose that option
now, as we will need one of these projects to complete our deployment process.

![create a blank project](../docs-images/blank_project.png)

After creating the project, make a note of the name that's generated for you -
you'll need this project name when deploying from the command line.

![project name](../docs-images/project_name.png)

In this example, the project name is `deep-zebra-47` - we'll use this as an
example name in the commands below.

### Create and export a Deploy access token

In order to use `deployctl` to control your Deno Deploy account from the command
line, you'll need an access token.

This token
[can be found in the dashboard here](https://dash.deno.com/account#access-tokens).
Click "New Access Token", give the token a name, and copy your newly minted
token to a secure location on your computer.

In your terminal, you'll need to export this token as a system environment
variable that can be used by `deployctl`.

<Tabs groupId="shells">
<TabItem value="bash" label="macOS / Linux" default>

```sh
export DENO_DEPLOY_TOKEN=your_access_token_here
```

</TabItem>

<TabItem value="powershell" label=" Windows (PowerShell)">

```powershell
$env:DENO_DEPLOY_TOKEN = 'your_access_token_here'
```

</TabItem>
</Tabs>

### Deploy!

Now that you have a project created and an access token created, you're ready to
deploy your application. In the same directory as the `server.ts` file you
created before, run this command:

```sh
deployctl deploy --project=deep-zebra-47 --prod server.ts
```

In a few moments, your Hello World server will be deployed across ~30 data
centers around the world, ready to handle large volumes of traffic.

## Usage

Expand Down
176 changes: 40 additions & 136 deletions deploy/manual/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,38 @@ response times. Deploy applications run on fast, light-weight
[V8 isolates](https://deno.com/blog/anatomy-isolate-cloud) rather than virtual
machines, powered by the [Deno runtime](/runtime/manual).

Let's deploy your first application - it should only take a few minutes.
Let's deploy your first application - it should only take a few minutes. The
easiest way to get start with Deno Deploy is to use [our Playground
editor](https://dash.deno.com/playground/example-helloworld). Clicking that link
will drop you into Hello World application, you can click the Fork button to
edit it.

The simplest Deno Deploy example is a web server that just returns a fixed
string for every response. It looks like this:

```js
Deno.serve(_req => {
return new Response("Hello, World!");
});
```

This server can also be built locally and run with the `deno` command line
runtime. If we create a file called `server.ts` on your computer, and include
the source code above. Then you can test that it works by running it with the
command below:

```
deno run --allow-net server.ts
```

Your server should be viewable at [localhost:8000](http://localhost:8000).
Now let's run this code on the edge with Deno Deploy!

Of course there are more advanced ways to deploy servers on Deno Deploy using
Github Integration or the `deployctl` command line utility. Here's of the
different ways to deploy:

## Option 1: Start with a template
## Option 1: Start with a template to build a github repo

If you'd like to start out by deploying a pre-built template application, simply
[log in to the Deno Deploy dashboard](https://dash.deno.com) and click the "New
Expand All @@ -29,143 +58,18 @@ Follow the on-screen instructions to deploy your existing application.

## Option 3: Start with a playground

A [playground](./playgrounds.md) is a browser-based editor that enables you to
write and run JavaScript code right away. This is a great choice for just
kicking the tires on Deno and Deno Deploy!
[From the Deno Deploy dashboard](https://dash.deno.com), click the "New Project"
button and choose any of the options with a "Try with a playground" button.
As mentioned above, a [playground](./playgrounds.md) is a browser-based editor
that enables you to write and run JavaScript code right away. This is a great
choice for just kicking the tires on Deno and Deno Deploy! [From the Deno Deploy
dashboard](https://dash.deno.com), click the "New Project" button and choose any
of the options with a "Try with a playground" button.

## Option 4: Start from scratch

If you'd like to develop and deploy a simple application locally, follow these
instructions to get started. We'll use the [`deployctl`](./deployctl.md) command
line utility to deploy a local Deno script from your computer.

### Install Deno and `deployctl`

If you haven't already, you can
[install the Deno runtime](/runtime/manual/getting_started/installation)
using one of the commands below:

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

<Tabs groupId="operating-systems">
<TabItem value="mac" label="macOS" default>

```sh
curl -fsSL https://deno.land/x/install/install.sh | sh
```

</TabItem>
<TabItem value="windows" label="Windows">

```powershell
irm https://deno.land/install.ps1 | iex
```

</TabItem>
<TabItem value="linux" label="Linux">

```sh
curl -fsSL https://deno.land/x/install/install.sh | sh
```

</TabItem>
</Tabs>

After Deno is installed, install the [`deployctl`](./deployctl.md) utility:

```
deno install -A --no-check -r -f https://deno.land/x/deploy/deployctl.ts
```

You can confirm `deployctl` has been installed correctly by running:

```
deployctl --help
```

Now, you're ready to deploy a Deno script from the command line!

### Write and test a Deno program

Create a file called `server.ts` in your terminal, and include the following
"Hello World" web server:

```ts title="server.ts"
Deno.serve(() => new Response("Hello, world!"));
```

You can test that it works by running it with the command below:

```
deno run --allow-net server.ts
```

Your server should be viewable at [localhost:8000](http://localhost:8000).
Now let's run this code on the edge with Deno Deploy!

### Sign up for Deno Deploy and create a blank project

If you haven't already, now is the time to
[sign up for a Deno Deploy account](https://dash.deno.com). After signing up,
[click the "New Project" button here](https://dash.deno.com). Near the top of
the page, you'll see an option to "create a blank project" - choose that option
now, as we will need one of these projects to complete our deployment process.

![create a blank project](../docs-images/blank_project.png)

After creating the project, make a note of the name that's generated for you -
you'll need this project name when deploying from the command line.

![project name](../docs-images/project_name.png)

In this example, the project name is `deep-zebra-47` - we'll use this as an
example name in the commands below.

### Create and export a Deploy access token

In order to use `deployctl` to control your Deno Deploy account from the
command line, you'll need an access token.

This token
[can be found in the dashboard here](https://dash.deno.com/account#access-tokens).
Click "New Access Token", give the token a name, and copy your newly minted token
to a secure location on your computer.

In your terminal, you'll need to export this token as a system environment
variable that can be used by `deployctl`.

<Tabs groupId="shells">
<TabItem value="bash" label="macOS / Linux" default>

```sh
export DENO_DEPLOY_TOKEN=your_access_token_here
```

</TabItem>

<TabItem value="powershell" label=" Windows (PowerShell)">

```powershell
$env:DENO_DEPLOY_TOKEN = 'your_access_token_here'
```

</TabItem>
</Tabs>

### Deploy!

Now that you have a project created and an access token created, you're ready
to deploy your application. In the same directory as the `server.ts` file you
created before, run this command:

```sh
deployctl deploy --project=deep-zebra-47 --prod server.ts
```

In a few moments, your Hello World server will be deployed across ~30 data
centers around the world, ready to handle large volumes of traffic.
If you'd like to develop and deploy a simple application locally, use the
[`deployctl`](https://github.com/denoland/deployctl)
command line utility. To learn more about how to use `deployctl` to follow [the
instructions here](./deployctl.md).

## Next Steps

Expand Down

0 comments on commit 5fb3eca

Please sign in to comment.