Starlette¶
Starlette is a lightweight ASGI framework/toolkit, which is ideal for building async web services in Python.
Note
For this guide, you should be familiar with the basic concepts of
Python and its package manager pip
Supervisord to set up your service
License¶
All relevant legal information can be found here
Prerequisites¶
Your URL needs to be setup:
[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$
Note
For this guide we will use mysite as the project’s name and will install it to ~/mysiteproject.
Installation¶
Install the latest Starlette version and ASGI server uvicorn.
[isabell@stardust ~]$ pip3.11 install --user starlette uvicorn
[isabell@stardust ~]$
Hint
For additional dependencies look at https://www.starlette.io/#dependencies .
Create Project¶
We create an example app in ~/mysiteproject/example.py:
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
async def homepage(request):
return JSONResponse({'hello': 'world'})
app = Starlette(debug=True, routes=[
Route('/', homepage),
])
Setup Service¶
Create Service¶
Now we continue with setting it up as a service.
Create ~/etc/services.d/mysite.ini with the following content:
[program:mysite]
directory=%(ENV_HOME)s/mysiteproject
command=uvicorn --host 0.0.0.0 example:app
startsecs=60
After creating the configuration, tell supervisord to refresh its configuration and start the service:
[isabell@stardust ~]$ supervisorctl reread
mysite: available
[isabell@stardust ~]$ supervisorctl update
mysite: updated process group
[isabell@stardust ~]$ supervisorctl status
mysite RUNNING pid 26020, uptime 0:03:14
[isabell@stardust ~]$
Your service should be in the state RUNNING. If it still is in STARTING instead, no worries! You might just have to wait sometime and try the command again (up to 15 seconds). It might already run fine anyway though. Otherwise check the logs in ~/logs/supervisord.log.
Configure Web Backend¶
Note
Uvicorn is running Starlette on port 8000 by default.
To make the application accessible from the outside, configure a web backend:
[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$
Your backend should now point to the service; let’s check it:
[isabell@stardust ~]$ uberspace web backend list
/ http:8000 => OK, listening: PID 23161, python3.11 /home/isabell/.local/bin/uvicorn --host 0.0.0.0 example:app
[isabell@stardust ~]$
Best practices¶
Security¶
Change all default passwords. Look at folder permissions. Don’t get hacked!
Updates¶
Note
Check the update feed regularly to stay informed about the newest version.
Tested with Starlette 0.31.1, Python 3.11, Uberspace 7.15
Written by: Lomion <lomion@sarkasti.eu>, brutus <brutus.dmc@googlemail.com>