Crate shuttle_runtime

Shuttle - Deploy Rust apps with a single Cargo subcommand

Hello, and welcome to the shuttle API documentation!

Shuttle is an open-source app platform that uses traits and annotations to configure your backend deployments.

Usage

Start by installing the cargo shuttle subcommand by running the following in a terminal:

$ cargo install cargo-shuttle

Now that shuttle is installed, you can initialize a project with Axum boilerplate:

$ cargo shuttle init --template axum my-axum-app

By looking at the Cargo.toml file of the generated my-axum-app project you will see it has been made to be a binary crate with a few dependencies including shuttle-runtime and shuttle-axum.

axum = "0.7.3"
shuttle-axum = "0.41.0"
shuttle-runtime = "0.41.0"
tokio = "1.28.2"

A boilerplate code for your axum project can also be found in src/main.rs:

use axum::{routing::get, Router};

async fn hello_world() -> &'static str {
    "Hello, world!"
}

#[shuttle_runtime::main]
async fn main() -> shuttle_axum::ShuttleAxum {
    let router = Router::new().route("/", get(hello_world));

    Ok(router.into())
}

Check out our docs to see all the frameworks we support, or our examples if you prefer that format.

Running locally

To test your app locally before deploying, use:

$ cargo shuttle run

You should see your app build and start on the default port 8000. You can test this using;

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

Deploying

You can deploy your service with the cargo shuttle subcommand too. But, you will need to authenticate with the shuttle service first using:

$ cargo shuttle login

This will open a browser window and prompt you to connect using your GitHub account.

Before you can deploy, you have to create a project. This will start a deployer container for your project under the hood, ensuring isolation from other users’ projects. PS. you don’t have to do this now if you did in in the cargo shuttle init flow.

$ cargo shuttle project start

Then, deploy the service with:

$ cargo shuttle deploy

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

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

Using sqlx

Here is a quick example to deploy a rocket service that uses a postgres database and sqlx:

Initialize a project with Rocket boilerplate:

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

Add shuttle-shared-db as a dependency with the postgres feature, and add sqlx as a dependency with the runtime-tokio-native-tls and postgres features inside Cargo.toml:

shuttle-shared-db = { version = "0.41.0", features = ["postgres"] }
sqlx = "0.7.1"

Now update the #[shuttle_runtime::main] function to take in a PgPool:

#[macro_use]
extern crate rocket;

use rocket::State;
use sqlx::PgPool;
use shuttle_rocket::ShuttleRocket;

struct MyState(PgPool);

#[get("/")]
fn hello(state: &State<MyState>) -> &'static str {
    // Do things with `state.0`...
    "Hello, Postgres!"
}

#[shuttle_runtime::main]
async fn rocket(#[shuttle_shared_db::Postgres] pool: PgPool) -> ShuttleRocket {
    let state = MyState(pool);
    let rocket = rocket::build().manage(state).mount("/", routes![hello]);

    Ok(rocket.into())
}

For a local run, shuttle will automatically provision a Postgres instance inside a Docker container on your machine and connect it to the PgPool.

For deploys, shuttle will provision a database for your application and connect it to the PgPool on your behalf.

To learn more about shuttle managed resources, see our resource docs.

Configuration

The cargo shuttle command can be customized by creating a Shuttle.toml in the same location as your Cargo.toml.

Change the name of your service

To have your service deployed with a different name, add a name entry in the Shuttle.toml:

name = "hello-world"

If the name key is not specified, the service’s name will be the same as the crate’s name.

Alternatively, you can override the project name on the command-line, by passing the –name argument to any subcommand like so:

$ cargo shuttle deploy --name=$PROJECT_NAME

Using Podman instead of Docker

If you are using Podman instead of Docker, then cargo shuttle run will give got unexpected error while inspecting docker container: error trying to connect: No such file or directory error.

To fix this error you will need to expose a rootless socket for Podman first. This can be done using:

podman system service --time=0 unix:///tmp/podman.sock

Now set the DOCKER_HOST environment variable to point to this socket using:

export DOCKER_HOST=unix:///tmp/podman.sock

Now all cargo shuttle run commands will work against Podman.

Getting API keys

After you’ve installed the cargo-shuttle command, run:

$ cargo shuttle login

this will open a browser window and prompt you to connect using your GitHub account.

Join Discord

If you have any questions, join our Discord server. There’s always someone on there that can help!

You can also open an issue or a discussion on GitHub.

Re-exports

• pub use tokio;

Structs

• DbInput
  The input given to Shuttle DB resources
• ResourceFactory
  A factory for getting metadata when building resources

Enums

• Error
  An error that can occur in the process of building and deploying a service.

Traits

• IntoResource
  Implement this on an ResourceInputBuilder::Output type to turn the base resource into the end type exposed to the Shuttle main function.
• ResourceInputBuilder
  Allows implementing plugins for the Shuttle main function.
• Service
  The core trait of the Shuttle platform. Every service deployed to Shuttle needs to implement this trait.

Type Aliases

• CustomError
  Type alias for an anyhow::Error.

Attribute Macros

• async_trait
• main
  Helper macro that generates the entrypoint required by any service - likely the only macro you need in this crate.