Skip to main content

Overview

This page provides an overview of getting your development environment ready for building Reboot applications. See the State page for more details on how you define the state stored by your application and the Servicers page for more information on how to implement the methods on your state.

Set up your environment​

You can use one of Reboot's GitHub Codespaces or set up your environment manually by installing the prerequisites listed below.

Prerequisites​

OS
Linuxx86_64, glibc>=2.35 (Ubuntu Jammy and other equivalent-generation distributions)
macOSarm64 or x86_64 macOS >= 13.0 and Xcode >= 14.3
  • Python == 3.10 is required for Python backends, and fetched automatically for Node.js backends
  • Node.js >= 18.0.0 is required for Node.js backends only
  • Docker
note

Your applications don't need to run "inside of" Docker, but Docker is used to host a service you need to use for local development.

Install rbt​

For Python you'll need the reboot package, and for TypeScript you'll need @reboot-dev/reboot.

rbt init​

The rbt init command initializes your Reboot project with a hello_world template. You can customize the project by selecting specific languages and platforms, and the tool will automatically update your .rbtrc configuration based on your selections.

Python backend​

To set up a Python backend, use the following command:

rbt init --name=reboot_hello_world --backend=python

This will generate the necessary source files and include a Python script to test the connection to the backend.

TypeScript backend​

For a TypeScript backend, use the following command:

rbt init --name=reboot_hello_world --backend=nodejs

This will create the source files and configure package.json if it doesn't already exist.

Frontend​

To initialize a frontend with React, use the following command:

rbt init --name=reboot_hello_world --frontend=react

This command generates the source files and sets up package.json in the web directory for the frontend.

note

You can initialize both backend and frontend simultaneously. Here are examples for Python and TypeScript:

For Python:

rbt init --name=reboot_hello_world --backend=python --frontend=react

For TypeScript:

npx rbt init --name=reboot_hello_world --backend=nodejs --frontend=react

Directory layout​

You can layout your directories how ever you like, as long as you pass them correctly to rbt.

Here is a suggested file layout:

FilesDirectory
*.protoapi/
Backend source *.py, *.ts/jsbackend/src
Backend tests *.py, *.ts/jsbackend/tests
Frontendweb

.rbtrc and flags​

rbt loads its flags from an .rbtrc file, if present. This is a convenient way of keeping the options you have to type and remember to a minimum.

An .rbtrc file might look like:

# Watch if any generated or source files are modified.
dev run --watch=backend/**/*.py

# Tell `rbt` that this is a Python application.
dev run --python

# Save state between chaos restarts.
dev run --name=bank

# Run the application!
dev run --application=backend/src/main.py

# When expunging, expunge that state we've saved.
dev expunge --name=bank

Syntax​

Global options​

Global options like the --state-directory flag can be specified in .rbtrc by prefixing with ...:

... --state-directory=non/default

Passthrough options​

Commands like protoc use the -- separator to accept arguments to pass directly to an underlying tool:

In a terminal:

rbt protoc --python=backend/api/ api/ -- --mypy_out=backend/api/

In .rbtrc:

# Find '.proto' files in 'api/'.
protoc api/

# Generate 'python' code from our '.proto' files in 'backend/api/'.
protoc --python=backend/api/

# Generate 'mypy' code from our '.proto' files in 'backend/api/mypy/'.
protoc -- --mypy_out=backend/api/mypy/

In these examples, the order of the flags is crucial. All flags that appear after -- are passed directly to protoc.

Boilerplate code​

The rbt protoc command can generate boilerplate code based on your .proto files, giving you copy-paste-able Python/TypeScript method definitions for which you only need to fill in the implementation. To generate the boilerplate code, use the --boilerplate flag followed by the path to the directory where you want the boilerplate code to be placed:

In Terminal:

rbt protoc --boilerplate=backend/boilerplate/

In .rbtrc:

protoc --boilerplate=backend/boilerplate/
note

It's important not to modify the generated files directly, as they will be overwritten the next time you run rbt protoc. Instead, you should copy (parts of) the generated files to your source directory and make your modifications there.

Running your app for development​

Once you've setup your environment as outlined above, all you'll need to run to start live developing your app is:

$ rbt dev run
...

Or if you're building a Node.js backend with npm (after installing @reboot-dev/reboot):

$ npx rbt dev run
...

Persisting state during development and rbt dev expunge​

By default your application state will not be persisted across restarts.

To persist state, you can pass a --name=... flag to rbt dev run. While this can be very useful while developing, it is designed to mimic a production environment and thus will not allow you to create any backwards incompatible changes in your .proto files.

This is great if your application is already running in production as it will keep you from causing production outages! But during early development of your application you might encounter a backwards incompatible change that is not an issue because you haven't deployed your application yet.

If you want to delete all of the state of a named application and start from scratch, use rbt dev expunge --name=... where --name=... is the same value you're using for rbt dev run.

Inspecting state​

While doing local development you can inspect your application state by pointing your browser at http://localhost:9991/__/inspect (assuming you aren't using TLS or haven't changed the default port from 9991).