Skip to content

Commit

Permalink
Merge pull request #84 from wasmerio/new-publish-deploy-docs
Browse files Browse the repository at this point in the history 
Add docs for the new deploy and publish flow
  • Loading branch information
@syrusakbary
syrusakbary authored May 20, 2024
2 parents adec4e0 + 333175c commit 632a985
Show file tree
Hide file tree
Showing 12 changed files with 941 additions and 738 deletions.
Binary file modified assets/deploy/quickstart/static-site.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/deploy/quickstart/updated-static-site.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
351 changes: 180 additions & 171 deletions pages/edge/cli.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,217 +1,226 @@
import { Callout } from "nextra-theme-docs";

# `wasmer app` and `wasmer deploy` CLI
# Managing your Wasmer Edge apps with the `wasmer` CLI
Wasmer provides you with CLI commands to deploy and manage your applications on the Edge.
The most important ones are `wasmer deploy` and the subcommands of `wasmer app`.

Wasmer provides you with commands in their CLI to deploy and manage your applications on the edge.

## Usage

Wasmer has two main commands for deploy:

- `wasmer app`
- `wasmer deploy`

<Callout type="info" emoji="ℹ️">
**Note:** You must be logged in to Wasmer to use the `app` and `deploy`
commands.
<Callout type="info">
**Note:** To deploy apps on Wasmer Edge, users need an account. When
deploying an app, users are prompted to login if they did not already.
</Callout>

### `wasmer app`

It allows the user to:

- Create an app
- Get information about an app
- List all of their apps

#### `wasmer app create`

This command is used to create an app that will be deployed on the edge.

This further provides you with options:

1. Use an existing package, like a `static-web-server` for static website.
2. Create your own custom app from scratch.

You can also specify an app type with the `--type` flag. The available types are:

- Static website
- HTTP server
- Browser shell **(coming soon)**
<Callout>
**Note:** This page describes in more detail the commands available in the
CLI to manage your Wasmer Edge apps. To quickly create and deploy an app,
refer to the [get started guide](/edge/get-started) or just
[install](/install) the CLI and run `wasmer deploy`.
</Callout>

#### `wasmer app get`
## Deploying an app (`wasmer deploy`)
To deploy an app to the Wasmer Edge, the user can use the `wasmer deploy` command.

This command is used to get the information about an app.

**Arguments**
```shell
$ wasmer deploy --help
Deploy an app to Wasmer Edge

- `ident`: The identifier of the app you want to get information about. This is an optional argument. If you do not provide an app identifier, it will automatically get that from your `app.yaml` file in your current directory. This is basically the `name` field in your `app.yaml` file.
Usage: wasmer deploy [OPTIONS]

**Options**
Options:

- `--format`: The format to use for the output. This defaults to `yaml`. Other options are `json` and `text`.
- `--token`: The token to use for authentication. You can also use the `WASMER_TOKEN` environment variable. This defaults to the token in your `~/.wasmer/wasmer.toml` file.
- `--verbose`: Show verbose output.
- `--quiet`: Do not print progress messages.
- `--color`: Whether to use colored output. Defaults to `auto`. Possible values are `auto`, `always`, and `never`.
--publish-package
Automatically publish the package referenced by this app.

Only works if the corresponding wasmer.toml is in the same directory.

```shell
$ wasmer app get wasmer/app-1
Loaded app config from: /path/to/your/app.yaml
---
id: da_4X8AGot5YVP2
name: app-1
created_at: "2023-06-15T11:46:46.642510+00:00"
description: ~
active_version:
id: dav_3XwGTWtYue3X
created_at: "2023-08-04T11:36:47.959492+00:00"
version: v1
description: ~
yaml_config: "kind: wasmer.io/App.v1\nmeta:\n description: ''\n name: wasmer/app-1\nspec:\n workload:\n source: wasmer/[email protected]\n"
user_yaml_config: "---\nkind: wasmer.io/App.v0\nname: app-1\napp_id: da_4X8AGot5YVP2\npackage: wasmer/[email protected]\n"
config: "{\"kind\": \"wasmer.io/App.v1\", \"meta\": {\"description\": \"\", \"name\": \"wasmer/app-1\"}, \"spec\": {\"workload\": {\"source\": \"wasmer/[email protected]\"}}}"
json_config: "{\"kind\": \"wasmer.io/App.v1\", \"meta\": {\"description\": \"\", \"name\": \"wasmer/app-1\"}, \"spec\": {\"workload\": {\"source\": \"wasmer/[email protected]\"}}}"
url: "https://rp9hmipc5rz2.id.wasmer.app"
app:
id: da_4X8AGot5YVP2
admin_url: "https://wasmer.io/apps/wasmer/app-1"
owner:
global_name: wasmer
url: "https://app-1.wasmer.app"
aliases:
page_info:
has_next_page: false
end_cursor: YXJyYXbjp25uNMN0aW9uOjA=
edges:
- node:
name: app-1
--path <PATH>
The path to the app.yaml file

--no-wait
Do not wait for the app to become reachable

--owner <OWNER>
Specify the owner (user or namespace) of the app.

If specified via this flag, the owner will be overridden. Otherwise,
the `app.yaml` is inspected and, if there is no `owner` field in the
spec file, the user will be prompted to select the correct owner. If
no owner is found in non-interactive mode the deployment will fail.
...
```
##### `wasmer app info`

This command is a less verbose version of `wasmer app get`. It will only show the app information that you might quickly need.

**Arguments**

- `ident`: The identifier of the app you want to get information about. This is an optional argument. If you do not provide an app identifier, it will automatically get that from your `app.yaml` file in your current directory. This is basically the `name` field in your `app.yaml` file.
The `wasmer deploy` command has many flags, but does not have any mandatory
argument. Its objective is that of loading the user-provided data - thus,
possibly, [publishing](/registry/cli) a package as well - in Wasmer Edge and
providing the needed informations for the user to manage their application.
Based on the kind of app the user wants to deploy, the `wasmer deploy`
command carries out different actions. In a nutshell, from the CLI perspective,
there are two kinds of deployment - just as mentioned above for the `wasmer app
create` command - which entail two different flows.
In one case the user refers to a package already existing in the registry - in
this case [the `package` field](/edge/configuration/app-configuration#package)
in the `app.yaml` file will refer to an identifier of the package (e.g.
`wasmer/hello`). In the other case, when the user has a custom local package
that they want to upload and use, the `package` field will contain the path to
the package's manifest.
In the latter case, the `wasmer deploy` command recognizes that the user
might want to edit some of the metadata about the package and, if needed,
prompts the user to decide on that regard. One example is that of the package
version: in interactive mode, if the `--bump` flag was not given, the user will
be asked if a patch version bump is needed. This, however, is not the only way
to specify the version of a package: for a deeper dive into this matter, check
out the [`publish` page](/registry/cli).
Once these matters are decided upon, this deployment flow concludes just as the
former: your app is available!
```shell
$ wasmer app info wasmer/app-1
Loaded app config from: /path/to/your/app.yaml
App Info
> App Name: app-1
> App URL: https://app-1.wasmer.app
> Versioned URL: https://rp9hmipc5rz2.id.wasmer.app
> Admin dashboard: https://wasmer.io/apps/wasmer/app-1
$ wasmer deploy
...
✔ Who should own this app? · <your-app>
✔ What should be the name of the app? · <your-app-name>
✔ What would you like to deploy? · Choose an existing package
✔ What is the name of the package? · wasmer/hello
✔ Unpacked template
✔ Do you want to deploy the app now? · yes
Deploying app <your-app-name> (<you>) to Wasmer Edge...
App <your-app-name> (<you>) was successfully deployed 🚀
https://<your-app-name>-<you>.wasmer.app
→ Unique URL: https://<app-id>.id.wasmer.app
→ Dashboard: https://wasmer.io/apps/<you>/<your-app-name>
Waiting for new deployment to become available...
(You can safely stop waiting now with CTRL-C)
.
𖥔 Deployment complete
```
#### `wasmer app list`
<Callout type="info">
**Note:** The `wasmer deploy` command is a _top level alias_ of
`wasmer app deploy`: running any of the two commands will result in the execution
of the same program.
</Callout>
This command will list all the apps you have deployed.
## Managing your app (`wasmer app` subcommand)
Once an app is deployed, the `wasmer` CLI provides a number of tools to manage
it.
**Options**
### Gathering informations about apps (`wasmer app info` and `wasmer app get`)
In order to fetch structured informations about your app, you can use the
`wasmer app get`, that provides the user with a number of informations about
the app structured as a YAML value, ranging from the identifier of the app to
the raw value of the `app.yaml` config file used to create the app.
- `--format`: The format to use for the output. This defaults to `table`. Other options are `json` and `text`.
-
The `wasmer app info` command provides a synthesis of these informations, in
particular the app name, the owner of the app, and relevant URLs.
```shell
$ wasmer app list
+------------------------------+---------+----------------------------------+-----------------+
| App | Version | Created | Id |
+=============================================================================================+
| wasmer/app-1 | v11 | 2023-03-01T16:43:19.828000+00:00 | da_DR9EIBt1**** |
|------------------------------+---------+----------------------------------+-----------------|
| wasmer/app-2 | v1 | 2023-05-19T16:05:44.461405+00:00 | da_onBBIbtX**** |
|------------------------------+---------+----------------------------------+-----------------|
| wasmer/app-3 | v15 | 2023-05-26T12:10:05.777287+00:00 | da_pKWgIvtQ**** |
+------------------------------+---------+----------------------------------+-----------------+
```

### `wasmer deploy`

This command is used to deploy an app. Running this command will automatically publish an app to the registry and then deploy it to the edge.
Once you have an `app.yaml` file, you can deploy it with the following command:

```shell
$ wasmer deploy
$ wasmer app info
App Info
→ Name: <your-app-name>
→ Owner: <you>
→ URL: https://<your-app-name>-<you>.wasmer.app
→ Unique URL: https://<app-id>.id.wasmer.app
→ Dashboard: https://wasmer.io/apps/<you>/<your-app-name>
```
For a complete guide on deploying an app, check the [edge get started guide](/edge/get-started).
Both these apps have the same user-facing structure: the user can provide an
app specifier in a format such as `your-name/your-app` or as the app
identifier, which is persisted in the `app.yaml` file upon deploying.
## Help
### Listing your apps (`wasmer app list`)
In order to show all the apps linked to your account, you can use the `wasmer app list` command.
This is the help output from the Wasmer CLI for `wasmer app --help`:
### Creating an app (`wasmer app create`)
The Wasmer CLI allows users to intentionally create an app, but if a user runs
`wasmer deploy` without an app available, the app creation process will be
triggered.
```shell
Usage: wasmer app <COMMAND>
$ wasmer app create --help
Create a new Edge app
Commands:
get Show an app
list List apps
logs Show an app
init Initialize apps with templates
help Print this message or the help of the given subcommand(s)
Usage: wasmer app create [OPTIONS]
Options:
-h, --help Print help
➜ ~ wasmer app --help
Manage Wasmer Edge apps

Usage: wasmer app <COMMAND>
-t, --type <type>
Possible values:
- http: A HTTP server
- static-website: A static website
- browser-shell: Wraps another package to run in the browser
- js-worker: Winter-js based JS-Worker
- py-application: Python worker
--deploy
Whether or not to deploy the application once it is created.
If selected, this might entail the step of publishing the package
related to the application. By default, the application is not
deployed and the package is not published.
-v, --verbose...
Generate verbose output (repeat for more verbosity)
Commands:
get Show an app
list List apps
logs Show an app
init Initialize apps with templates
help Print this message or the help of the given subcommand(s)

Options:
-h, --help Print help
```

This is the help output from the Wasmer CLI for `wasmer deploy --help`:
--no-validate
Skip local schema validation
...
```
Usage: wasmer deploy [OPTIONS] [PATH]
Arguments:
[PATH]
The path to a YAML file with the deploy config
Options:
--token <TOKEN>
[env: WASMER_TOKEN=]
--registry <REGISTRY>
This subcommand offers a wide range of flags, mostly to make `wasmer app
create` functional as a non-interactive command as well.
In the interactive case, the user will be guided through the steps to create an
app: entering the name of the owner of the app (if not
provided via the `--owner` flag) and the name of the app (if not provided via
the `--name` flag).
-f, --format <FORMAT>
Output format. (json, text)
Once the metadata about the app are available, the user must decide the _kind_
of app they want to deploy.
[default: yaml]
```shell
$ wasmer app create
...
? What would you like to deploy? ›
Start with a template
❯ Choose an existing package
```
--no-validate
Skip local schema validation
{/* [TODO]: Add link to templates list */}
--publish-package
Automatically publish the package referenced by this app.
Templates allow users to kickstart their custom application from one of the
available boilerplates like a static website, a php application, a javascript
worker and much more. Another possibility is that of creating an app from an
existing package: for example, as a starting step, the user can create the app
from an existing package, like
[`wasmer/hello`](https://wasmer.io/wasmer/hello).
Only works if the corresponding wasmer.toml is in the same directory.
```shell
$ wasmer app create
...
✔ What would you like to deploy? · Choose an existing package
✔ What is the name of the package? · wasmer/hello
```
The result of this action is that the CLI will create a file called `app.yaml`
in the current working directory:
```
kind: wasmer.io/App.v0
name: <YOUR-APP-NAME>
owner: <YOUR-NAME>
package: wasmer/hello
```
--non-interactive
Do not prompt for user input
This file contains all the necessary informations required to deploy your app
to Wasmer Edge. To learn more about this configuration file, refer to the
[dedicated _Learn_ page](/edge/learn/apps). After having everything in place -
whether it is from templates or pre-existing packages - the command will ask
the user if they want to _deploy_ their app.
-h, --help
Print help (see a summary with '-h')
```
The arguments for this command are:
- `--token`: The token to use for authentication. You can also use the `WASMER_TOKEN` environment variable. This defaults to the token in your `~/.wasmer/wasmer.toml` file.
- `--registry`: The registry to use. This defaults to the active registry in your `~/.wasmer/wasmer.toml` file.
- `--format`: The format to use for the output. This defaults to `yaml`.
- `--no-validate`: Skip local schema validation.
- `--publish-package`: Automatically publish the package referenced by this app. Only works if the corresponding `wasmer.toml` is in the same directory.
- `--non-interactive`: Do not prompt for user input.
Loading

0 comments on commit 632a985

Please sign in to comment.