Local runs with databases
If your project uses a database resource, it will default to starting a local Docker container for that database. If you’d like to opt out of this behavior and supply your own database URI, simply pass it in as an argument to your resource. This argument also supports insertion of secrets fromSecrets.toml
with string interpolation:
IMPORTANT: If Docker isn’t started, you may receive an “os error 2” error. This is typically related to your Docker installation. If you’re using Docker via the CLI, you can use any Docker command to start it up. If you’re using Docker Desktop, you will need to start Docker Desktop.
If Docker fails to launch the database container, sometimes pulling the image manually (
docker pull postgres:16
) can help resolve it.To recreate a local database, use
docker ps
to find the postgres container, then docker stop
and docker rm
to delete it. On the next run, a new one will be created.Expose your application to your local network
If you’d like to expose your application to you local network, for example if you’re serving a static website and you’d like to open it on your phone, simply pass in the--external
flag:
0.0.0.0:8000
, and you will now be able to connect to it
using your computer’s local IP. If you’d also like to change the port, you can do so with the --port
argument:
You may need to open the port your app is started on in your firewall.
Development Tips
Here are some small tips and tricks to boost your productivity when developing locally.Live reload backend with bacon
To live reload your Shuttle app when you save a file, you can install bacon and then use
shuttle run
when you save a file.
To customize this behavior, you can set up your own jobs in bacon.toml
.
Shuttle’s default bacon config can be found here.
Live reload backend with cargo watch
cargo-watch
is no longer maintained, but still works.ignore
will also affect the behaviour of shuttle deploy
.
See the documentation on including ignored files for more info.
Live reload frontend with tower-livereload
Using bacon
or cargo watch
will only reload the “backend” Shuttle process.
If you are developing a frontend in the browser that is hosted by your Shuttle app,
you might also want the web page to reload when files change.
If you are using Axum or other Tower-compatible frameworks, the Tower layer tower-livereload can help you.
First, add it to your project:
cargo watch
!
If you want to exclude this functionality from the release build, add this:
Docker engines
cargo-shuttle
uses the bollard crate to interact with the Docker engine on local runs.
If you are using a non-standard Docker engine, you might get this error:
unix:///var/run/docker.sock
unless the DOCKER_HOST
env variable overrides it.
If you end up using a DOCKER_HOST
like below, you can add the export DOCKER_HOST=...
line to your shell’s config file to have it automatically set in new shell sessions.
Docker Desktop
Podman
You will need to expose a rootless socket for Podman, and then set theDOCKER_HOST
environment variable: