Creating an app from the template#
The best way to create a new Safir-based application is with the fastapi_safir_app template.
The quickest way to do this is by running the /msg @Squarebot create project
Slack command on the Rubin project Slack.
For a manual equivalent, see Manually creating an app from the template.
1. Install necessary prerequisites#
For local development, you will need Python 3.13 or later installed locally. The fastapi_safir_app template does not support earlier versions.
You will also need to have a recent version of uv installed locally. See the uv documentation for installation instructions.
2. Create the project#
In the Rubin Observatory internal project Slack, ask SQuaRE Bot to create a new project:
/msg @Squarebot create project
Select the FastAPI application (Safir)
template.
This will ask a series of questions to configure your new repository, and then create it from the fastapi_safir_app template.
If you are creating a UWS service, select the UWS
flavor.
3. Clone the repository#
SQuaRE Bot will create a new GitHub repository and notify you when that is complete. Check out that new repository with Git using the command that Squarebot gives you. You will be able to interact with this repository like any other GitHub repository.
4. Initialize the dependencies#
Start by creating and activating a local virtual environment for development.
uv venv
source .venv/bin/activate
You may use other ways to manage your virtual environment if you choose, but using per-checkout virtual environments managed by uv is usually the most convenient and robust.
Now run the initialization command:
make update
This command does several important things for you:
Based on the dependencies listed in
pyproject.toml
, creates a lockfile of the latest compatible versions of every dependency inuv.lock
.Installs your project in a locally editable mode, along with the third-party dependencies listed in
uv.lock
.Installs tox.
Installs pre-commit hooks.
After the dependencies are locked, commit the uv lockfile:
git add uv.lock
git commit
Note
None of the versions of your project’s dependencies will change until you explicitly update them.
In the future, you can update the dependencies by re-running make update
and re-committing the uv.lock
file.
To install the project for development without updating dependencies, run:
make init
5. Format code with Ruff#
The Python code generated by the template is valid, but there may be minor formatting issues related to line length and your application’s chosen name. You can format the code by running tox:
tox run -e lint
git commit -a
6. Try the local test commands#
The preferred way to run tests is with tox:
tox run
Tox runs several test steps, each in their own virtual environment. To learn about these test steps:
tox list
For example, to only run mypy to check type annotations:
tox run -e typing
Or to only lint the code (and reformat it):
tox run -e lint
To run all the default test steps, but in parallel:
tox run-parallel -p auto
7. Try the local development server#
In addition to running tests, tox is also configured with a command to spin up a development server:
tox run -e run
In another shell, send an HTTP GET request to the development server:
curl http://localhost:8000/ | python -m json.tool
This development server auto-reloads, so any time you change the code, the server will restart for you.
Next steps#
Now that you have a working application repository, the next steps are to develop your application’s logic and interface, and then deploy it to Phalanx.
To learn learn more about developing Safir-based applications like yours, refer to the guides in this documentation and the FastAPI documentation.
To learn how to deploy your application to Phalanx, see the Phalanx developer documentation.