|
4 | 4 | # cargo-shuttle |
5 | 5 |
|
6 | 6 | <p align=center> |
7 | | - <a href="https://docs.rs/shuttle-service"> |
| 7 | + <a href="https://docs.shuttle.rs/"> |
8 | 8 | <img alt="docs" src="https://img.shields.io/badge/docs-reference-orange"> |
9 | 9 | </a> |
10 | 10 | <a href="https://github.com/shuttle-hq/shuttle/search?l=rust"> |
11 | 11 | <img alt="language" src="https://img.shields.io/badge/language-Rust-orange.svg"> |
12 | 12 | </a> |
13 | | - <a href="https://circleci.com/gh/shuttle-hq/shuttle/"> |
14 | | - <img alt="build status" src="https://circleci.com/gh/shuttle-hq/shuttle.svg?style=shield"/> |
15 | | - </a> |
16 | 13 | <a href="https://discord.gg/shuttle"> |
17 | 14 | <img alt="discord" src="https://img.shields.io/discord/803236282088161321?logo=discord"/> |
18 | 15 | </a> |
19 | 16 | </p> |
20 | 17 | <!-- markdownlint-restore --> |
21 | | -<!-- markdownlint-disable MD001 --> |
22 | | - |
23 | | -`cargo-shuttle` is your commandline tool for deploying web apps on [shuttle](https://www.shuttle.rs/), the stateful serverless web platform for Rust. |
24 | 18 |
|
25 | | -**README Sections:** [Installation](#installation) — [Subcommands](#subcommands) — [Development](#development) |
| 19 | +`cargo-shuttle` is the command line tool for deploying Rust apps on [Shuttle](https://www.shuttle.rs/), the Rust-native cloud deployment platform. |
26 | 20 |
|
27 | 21 | </div> |
28 | 22 |
|
29 | | ---- |
30 | | - |
31 | | -`cargo-shuttle` brings [shuttle](https://www.shuttle.rs/), 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. |
32 | | - |
33 | | ---- |
34 | | - |
35 | | -<!-- markdownlint-disable-next-line --> |
36 | | -<a id="installation"><h1>Installation</h1></a> |
| 23 | +## Installation |
37 | 24 |
|
38 | | -`cargo-shuttle` is available for macOS, Linux, and Windows. |
| 25 | +For the full list of installation options, refer to the [Installation docs](https://docs.shuttle.rs/getting-started/installation). |
39 | 26 |
|
40 | | -To install on Linux or macOS, run: |
| 27 | +Linux and macOS: |
41 | 28 |
|
42 | 29 | ```sh |
43 | 30 | curl -sSfL https://www.shuttle.rs/install | bash |
44 | 31 | ``` |
45 | 32 |
|
46 | | -On Windows, you can default to installing from source: |
47 | | - |
48 | | -```bash |
49 | | -cargo install cargo-shuttle |
50 | | -``` |
51 | | - |
52 | | -### Distro Packages |
53 | | - |
54 | | -<!-- markdownlint-disable-next-line --> |
55 | | -<details> |
56 | | -<!-- markdownlint-disable-next-line --> |
57 | | - <summary>Packaging status</summary> |
58 | | - |
59 | | -[](https://repology.org/project/cargo-shuttle/versions) |
60 | | - |
61 | | -</details> |
62 | | - |
63 | | -#### Arch Linux |
64 | | - |
65 | | -`cargo-shuttle` can be installed from the [extra repository](https://archlinux.org/packages/extra/x86_64/cargo-shuttle) using [pacman](https://wiki.archlinux.org/title/Pacman): |
66 | | - |
67 | | -```sh |
68 | | -pacman -S cargo-shuttle |
69 | | -``` |
70 | | - |
71 | | -#### Alpine Linux |
72 | | - |
73 | | -`cargo-shuttle` is available for [Alpine Edge](https://pkgs.alpinelinux.org/packages?name=cargo-shuttle&branch=edge). It can be installed via [apk](https://wiki.alpinelinux.org/wiki/Alpine_Package_Keeper) after enabling the [testing repository](https://wiki.alpinelinux.org/wiki/Repositories). |
74 | | - |
75 | | -```sh |
76 | | -apk add cargo-shuttle |
77 | | -``` |
78 | | - |
79 | | ---- |
80 | | - |
81 | | -<!-- markdownlint-disable-next-line --> |
82 | | -<a id="subcommands"><h1>Subcommands</h1></a> |
83 | | - |
84 | | -`cargo-shuttle`'s subcommands help you build and deploy web apps from start to finish. |
85 | | - |
86 | | -Run `cargo shuttle help` to see the basic usage: |
87 | | - |
88 | | -```text |
89 | | -Usage: cargo-shuttle [OPTIONS] <COMMAND> |
90 | | -
|
91 | | -Commands: |
92 | | - init Create a new shuttle project |
93 | | - run Run a shuttle service locally |
94 | | - deploy Deploy a shuttle service |
95 | | - deployment Manage deployments of a shuttle service |
96 | | - status View the status of a shuttle service |
97 | | - stop Stop this shuttle service |
98 | | - logs View the logs of a deployment in this shuttle service |
99 | | - project List or manage projects on shuttle |
100 | | - resource Manage resources of a shuttle project |
101 | | - clean Remove cargo build artifacts in the shuttle environment |
102 | | - login Login to the shuttle platform |
103 | | - logout Log out of the shuttle platform |
104 | | - generate Generate shell completions and man page |
105 | | - feedback Open an issue on GitHub and provide feedback |
106 | | - help Print this message or the help of the given subcommand(s) |
107 | | -
|
108 | | -Options: |
109 | | - --working-directory <WORKING_DIRECTORY> Specify the working directory [default: .] [aliases: wd] |
110 | | - --name <NAME> Specify the name of the project (overrides crate name) |
111 | | - --api-url <API_URL> Run this command against the API at the supplied URL (allows targeting a custom deployed instance for this command only, mainly |
112 | | - for development) [env: SHUTTLE_API=] |
113 | | - -h, --help Print help |
114 | | - -V, --version Print version |
115 | | -``` |
116 | | - |
117 | | -### Subcommand: `init` |
118 | | - |
119 | | -To initialize a shuttle project with boilerplates, run `cargo shuttle init [OPTIONS] [PATH]`. |
120 | | - |
121 | | -Currently, `cargo shuttle init` supports the following frameworks: |
122 | | - |
123 | | -- `--template actix-web`: for [actix web](https://actix.rs/) framework |
124 | | -- `--template axum`: for [axum](https://github.com/tokio-rs/axum) framework |
125 | | -- `--template loco`: for [loco](https://github.com/loco-rs/loco) framework |
126 | | -- `--template poem`: for [poem](https://github.com/poem-web/poem) framework |
127 | | -- `--template poise`: for [poise](https://github.com/serenity-rs/poise) discord bot framework |
128 | | -- `--template rocket`: for [rocket](https://rocket.rs/) framework |
129 | | -- `--template salvo`: for [salvo](https://salvo.rs/) framework |
130 | | -- `--template serenity`: for [serenity](https://github.com/serenity-rs/serenity) discord bot framework |
131 | | -- `--template thruster`: for [thruster](https://github.com/thruster-rs/Thruster) framework |
132 | | -- `--template tide`: for [tide](https://github.com/http-rs/tide) framework |
133 | | -- `--template tower`: for [tower](https://github.com/tower-rs/tower) library |
134 | | -- `--template warp`: for [warp](https://github.com/seanmonstar/warp) framework |
135 | | - |
136 | | -For example, running the following command will initialize a project for [rocket](https://rocket.rs/): |
137 | | - |
138 | | -```sh |
139 | | -cargo shuttle init --template rocket my-rocket-app |
140 | | -``` |
141 | | - |
142 | | -This should generate the following dependency in `Cargo.toml`: |
143 | | - |
144 | | -```toml |
145 | | -rocket = "0.5.0" |
146 | | -shuttle-rocket = "0.39.0" |
147 | | -shuttle-runtime = "0.39.0" |
148 | | -tokio = "1.26.0" |
149 | | -``` |
150 | | - |
151 | | -The following boilerplate code should be generated into `src/lib.rs`: |
152 | | - |
153 | | -```rust |
154 | | -#[macro_use] |
155 | | -extern crate rocket; |
156 | | - |
157 | | -#[get("/")] |
158 | | -fn index() -> &'static str { |
159 | | - "Hello, world!" |
160 | | -} |
161 | | - |
162 | | -#[shuttle_runtime::main] |
163 | | -async fn rocket() -> shuttle_rocket::ShuttleRocket { |
164 | | - let rocket = rocket::build().mount("/", routes![index]); |
| 33 | +Windows (powershell): |
165 | 34 |
|
166 | | - Ok(rocket.into()) |
167 | | -} |
| 35 | +```powershell |
| 36 | +iwr https://www.shuttle.rs/install-win | iex |
168 | 37 | ``` |
169 | 38 |
|
170 | | -### Subcommand: `run` |
| 39 | +Build from source: |
171 | 40 |
|
172 | | -To run the shuttle project locally, use the following command: |
173 | | - |
174 | | -```sh |
175 | | -# Inside your shuttle project |
176 | | -cargo shuttle run |
177 | | -``` |
178 | | - |
179 | | -This will compile your shuttle project and start it on the default port `8000`. Test it by: |
180 | | - |
181 | | -```sh |
182 | | -$ curl http://localhost:8000 |
183 | | -Hello, world! |
184 | | -``` |
185 | | - |
186 | | -### Subcommand: `login` |
187 | | - |
188 | | -Use `cargo shuttle login` inside your shuttle project to generate an API key for the shuttle platform: |
189 | | - |
190 | | -```sh |
191 | | -# Inside a shuttle project |
192 | | -cargo shuttle login |
193 | | -``` |
194 | | - |
195 | | -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: |
196 | | - |
197 | | -```sh |
198 | | -cargo shuttle login --api-key <your-api-key-from-browser> |
199 | | -``` |
200 | | - |
201 | | -### Subcommand: `deploy` |
202 | | - |
203 | | -To deploy your shuttle project to the cloud, run: |
204 | | - |
205 | | -```sh |
206 | | -cargo shuttle project start |
207 | | -cargo shuttle deploy |
208 | | -``` |
209 | | - |
210 | | -Your service will immediately be available at `{crate_name}.shuttleapp.rs`. For instance: |
211 | | - |
212 | | -```sh |
213 | | -$ curl https://my-rocket-app.shuttleapp.rs |
214 | | -Hello, world! |
215 | | -``` |
216 | | - |
217 | | -### Subcommand: `status` |
218 | | - |
219 | | -Check the status of your deployed shuttle project with: |
220 | | - |
221 | | -```sh |
222 | | -cargo shuttle status |
223 | | -``` |
224 | | - |
225 | | -### Subcommand: `logs` |
226 | | - |
227 | | -Check the logs of your deployed shuttle project with: |
228 | | - |
229 | | -```sh |
230 | | -cargo shuttle logs |
| 41 | +```bash |
| 42 | +cargo install cargo-shuttle |
231 | 43 | ``` |
232 | 44 |
|
233 | | -### Subcommand: `stop` |
234 | | - |
235 | | -Once you are done with a deployment, you can stop it by running: |
| 45 | +## Documentation |
236 | 46 |
|
237 | | -```sh |
238 | | -cargo shuttle stop |
239 | | -``` |
| 47 | +Run `cargo shuttle help` to see the basic usage. |
240 | 48 |
|
241 | | ---- |
| 49 | +Full list of commands and more documentation can be viewed on the [CLI docs](https://docs.shuttle.rs/getting-started/shuttle-commands). |
242 | 50 |
|
243 | | -<!-- markdownlint-disable-next-line --> |
244 | | -<a id="development"><h1>Development</h1></a> |
| 51 | +## Development |
245 | 52 |
|
246 | 53 | Thanks for using `cargo-shuttle`! We’re very happy to have you with us! |
247 | 54 |
|
|
0 commit comments