cargo-shuttle

cargo-shuttle is your commandline tool for deploying web apps on shuttle, the stateful serverless web platform for Rust.

README Sections: Installation — Subcommands — Development

cargo-shuttle brings shuttle, the open source serverless platform for Rust web applications, into your terminal. With a dedicated focus on productivity, reliability, and performance, cargo-shuttle makes deploying your code to the cloud as easy as deriving a trait.

cargo-shuttle is available for macOS, Linux, and Windows. To install the commandline tool, run:

$ cargo install cargo-shuttle

cargo-shuttle's subcommands help you build and deploy web apps from start to finish.

Run cargo-shuttle --help to see the basic usage:

USAGE:
    cargo-shuttle [OPTIONS] <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --api-url <api-url>
            Run this command against the api at the supplied url [env: SHUTTLE_API=]

        --name <name>                              Specify the name of the project (overrides crate name)
        --working-directory <working-directory>    Specify the working directory [default: .]

SUBCOMMANDS:
    auth      create user credentials for the shuttle platform
    delete    delete the latest deployment for a shuttle project
    deploy    deploy a shuttle project
    help      Prints this message or the help of the given subcommand(s)
    init      create a new shuttle project
    login     login to the shuttle platform
    logs      view the logs of a shuttle project
    run       run a shuttle project locally
    status    view the status of a shuttle project

Subcommand: init

To initialize a shuttle project with boilerplates, run cargo shuttle init [OPTIONS] [PATH].

Currently, cargo shuttle init supports the following frameworks:

• --axum: for axum framework
• --poem: for poem framework
• --rocket: for rocket framework
• --tide: for tide framework
• --tower: for tower library

For example, running the following command will initialize a project for rocket:

$ cargo shuttle init --rocket my-rocket-app

This should generate the following dependency in Cargo.toml:

shuttle-service = { version = "0.5.1", features = ["web-rocket"] }

The following boilerplate code should be generated into src/lib.rs:

#[macro_use]
extern crate rocket;

use shuttle_service::ShuttleRocket;

#[get("/hello")]
fn hello() -> &'static str {
    "Hello, world!"
}

#[shuttle_service::main]
async fn init() -> ShuttleRocket {
    let rocket = rocket::build().mount("/", routes![hello]);

    Ok(rocket)
}

Subcommand: run

To run the shuttle project locally, use the following command:

# Inside your shuttle project
$ cargo shuttle run

This will compile your shuttle project and start it on the default port 8000. Test it by:

$ curl http://localhost:8000/hello
Hello, world!

Subcommand: login

Use cargo shuttle login inside your shuttle project to generate an API key for the shuttle platform:

# Inside a shuttle project
$ cargo shuttle login

This should automatically open a browser window with an auto-generated API key for your project. Simply copy-paste the API key back in your terminal or run the following command to complete login:

$ cargo shuttle login --api-key your-api-key-from-browser

Subcommand: deploy

To deploy your shuttle project to the cloud, run:

$ cargo shuttle deploy

Your service will immediately be available at {crate_name}.shuttleapp.rs. For instance:

$ curl https://my-rocket-app.shuttleapp.rs/hello
Hello, world!

Subcommand: status

Check the status of your deployed shuttle project with:

$ cargo shuttle status

Subcommand: logs

Check the logs of your deployed shuttle project with:

$ cargo shuttle logs

Subcommand: auth

Run the following to create user credentials for shuttle platform:

$ cargo shuttle auth your-desired-username

Subcommand: delete

Once you are done with a deployment, you can delete it by running:

$ cargo shuttle delete

Thanks for using cargo-shuttle! We’re very happy to have you with us!

During our alpha period, API keys are completely free and you can deploy as many services as you want.

Just keep in mind that there may be some kinks that require us to take all deployments down once in a while. In certain circumstances we may also have to delete all the data associated with those deployments.

To contribute to cargo-shuttle or stay updated with our development, please open an issue, discussion or PR on Github and join our Discord! 🚀