Deploying ASGI sites on PythonAnywhere (beta)

Disclaimer

This help page explains how to set up an ASGI site on PythonAnywhere -- for example, one based on the FastAPI framework, or using the latest Django async features.

Note: deployment of ASGI (and other async) websites on PythonAnywhere is an experimental feature. Some important limitations to know about:

  • HTTPS is only available on default PythonAnywhere subdomains (e.g. YOURUSERNAME.pythonanywhere.com).
  • There is no support for static file mappings.
  • There is no web UI for creating and managing ASGI websites -- it's API and command-line only.
  • We do not guarantee that the command line syntax and the API interface will remain the same.
  • We have not worked out the long-term pricing for ASGI sites, which will probably differ from the way we charge for traditional WSGI ones. We're 99.9% certain that there will be a way to host them in a free plan, though!

If you are brave enough to try it, here is a quick guide on how to do it :-)

Prerequisites

API token

This help page explains how to manage your websites using our pa command-line tool rather than the API, but you'll need to generate an API token so that that tool knows how to connect to PythonAnywhere.

To do that, log in to PythonAnywhere, and go to the "Account" page using the link at the top right. Click on the "API token" tab; if you don't already have a token, it will look like this:

API token not set up

Click the "Create a new API token" button to get your token, and you'll see this:

API token set up

That string of letters and numbers (masked out in the screenshot) is the API token, and anyone who has it can access your PythonAnywhere account and do stuff -- so keep it secret. If someone does somehow get hold of it, you can revoke it on this page by clicking the red button -- that stops it from working in the future, and creates a new one for you to use.

Now you can use our command-line tool or our experimental API to deploy your ASGI website. This help page will show you how to use the command-line tool, so you don't need to note down the API token -- now that it has been generated, it's available to any code running inside Bash consoles on PythonAnywhere.

Installing the command-line tools

As a first step, start a fresh Bash console, and in there, install the latest version of our command-line tool.

pip install --upgrade pythonanywhere

(As of this writing, it will print out an error about typing-extensions, but you can ignore that.)

Running that install will make a new command, pa available, which we'll be using later.

Creating a simple test website

Now we'll create a simple site that we can deploy. Exactly how you do that depends on the web framework you want to use:

FastAPI

Firstly, create a virtual environment with fastapi and uvicorn installed. In your Bash console:

mkvirtualenv my_venv --python=python3.10

...and then:

pip install "uvicorn[standard]" fastapi

Next, we'll create a minimal FastAPI site. Create a directory ~/my_fastapi/ and inside it create a file called main.py, containing the following code:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message":"Hello from FastAPI"}

That's enough setup! The only other thing you'll need to know to run your site is the command that you will later on provide when creating it; we'll explain the details of this later on, but for now, just note down that it should be this:

/home/YOURUSERNAME/.virtualenvs/my_venv/bin/uvicorn --app-dir /home/YOURUSERNAME/my_fastapi --uds $DOMAIN_SOCKET main:app

...with YOURUSERNAME replaced by your actual username, but with everything else exactly as it is.

Now you can move on to creating your website

Django

Firstly, create a virtual environment with django and uvicorn installed. In your Bash console:

mkvirtualenv my_venv --python=python3.10

...and then:

pip install "uvicorn[standard]" django

Next, we'll create a minimal Django site. Firstly, in your Bash console, run this:

django-admin startproject asyncdjango

Modify ~/asyncdjango/asyncdjango/urls.py to look like this:

from django.urls import path
from django.http import JsonResponse


async def async_view(request):
    return JsonResponse({'message': 'Hello from async Django!'})

urlpatterns = [
    path("", async_view),
]

That's enough setup! The only other thing you'll need to know to run your site is the command that you will later on provide when creating it; we'll explain the details of this later on, but for now, just note down that it should be this:

/home/YOURUSERNAME/.virtualenvs/my_venv/bin/uvicorn --app-dir /home/YOURUSERNAME/asyncdjango --uds $DOMAIN_SOCKET asyncdjango.asgi:application

...with YOURUSERNAME replaced by your actual username, but with everything else exactly as it is.

Now you can move on to creating your website

Managing your website

Creating your website

In Bash, to deploy your website to your subdomain -- that is, to yourusername.pythonanywhere.com if you're on our US system, or yourusername.eu.pythonanywhere.com if you're on the EU system -- just run the following. You'll need to replace the domain argument as appropriate, and put the framework-specific command that you noted down earlier inside the single quotes in place of COMMAND.

pa website create --domain YOURUSERNAME.pythonanywhere.com --command 'COMMAND'

If everything was successful, you should see something like:

< All done! Your site is now live at YOURUSERNAME.pythonanywhere.com. >
   \
    ~<:>>>>>>>>>

Now, if you go to the website URL defined in domain you should get something back from your website -- exactly what, of course, depends on which of the frameworks you chose agove.

Note: as of this writing, there is a bug that means that you might get a 404 not found page for a few seconds before the site comes up. If you get that, just refresh the page in your browser. We're on the case :-)

You have a working ASGI website hosted on PythonAnywhere! However, this site will not currently appear on the "Web" page inside your PythonAnywhere account; we have a user interface that is a work-in-progress, though, and if you'd like to try that out, drop us a line.

Getting and listing websites

You can get a list of ASGI websites from PythonAnywhere with this command:

pa website get

You'll get something like this:

domain name                      enabled
-------------------------------  ---------
YOURUSERNAME.pythonanywhere.com  True

And you can get the details for one website like this:

pa website get --domain YOURUSERNAME.pythonanywhere.com

...which will display something like this (the command will of course vary based on the framework you're using):

-----------  -------------------------------------------------------------------------------------------------------------------------
domain name  YOURUSERNAME.pythonanywhere.com
enabled      True
command      /home/YOURUSERNAME/.virtualenvs/my_venv/bin/uvicorn --app-dir /home/YOURUSERNAME/my_fastapi --uds $DOMAIN_SOCKET main:app
-----------  -------------------------------------------------------------------------------------------------------------------------

Reloading

If you change the code of your website, you'll need to reload it to activate those changes:

pa website reload --domain YOURUSERNAME.pythonanywhere.com

If all goes well, you'll see this:

< Website YOURUSERNAME.pythonanywhere.com has been reloaded! >
   \
    ~<:>>>>>>>>>

...and if you visit the site, you'll see that it's been updated to run your new code.

Delete

To delete your website, use this:

pa website delete --domain YOURUSERNAME.pythonanywhere.com

If all goes well, you'll see this:

< Website YOURUSERNAME.pythonanywhere.com has been deleted! >
   \
    ~<:>>>>>>>>>

...and the website will be gone, and replaced with our default "Coming Soon!" page.

Supported UI features

Logs

You can access the logs -- the ones that were printed out by the detailed version of the pa website get command -- from the Files page or from a console; they're located in /var/log.

The error log

For example, /var/log/YOURUSERNAME.pythonanywhere.com.error.log.

By default, uvicorn logs its status messages to the standard error stream, so if all is well you'll see something like this:

INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on unix socket /var/sockets/YOURUSERNAME.pythonanywhere.com/app.sock (Press CTRL+C to quit)

The last line is uvicorn saying that it has successfully started, and is listening for incoming requests on an internal unix domain socket. That socket is internal to our web-hosting system -- you won't be able to see it in a console or on the "Files" page inside PythonAnywhere.

The server log

For example, /var/log/YOURUSERNAME.pythonanywhere.com.server.log.

By default, uvicorn logs incoming requests to the standard output stream, so you'll see something like this:

INFO:      - "GET / HTTP/1.1" 200 OK
The access log

For example, /var/log/YOURUSERNAME.pythonanywhere.com.access.log.

This will also show incoming requests, but will be formatted similarly to other PythonAnywhere websites -- for example:

1.2.3.4 - - [17/Oct/2023:13:14:00 +0000] "GET / HTTP/1.1" 200 32 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36" "1.2.3.4" response-time=0.286

Technical details

If you just want to get an ASGI site up and running, all you need to do is follow the recipe above. However, if you'd like to understand a bit more about what is going on, or to build on these instructions to do more than just ASGI, read on!

As an example, let's use the command that we specified for FastAPI

/home/YOURUSERNAME/.virtualenvs/my_venv/bin/uvicorn --app-dir /home/YOURUSERNAME/my_fastapi --uds $DOMAIN_SOCKET main:app

Breaking that down:

  • /home/YOURUSERNAME/.virtualenvs/my_venv/bin/uvicorn is the path to uvicorn in your virtualenv. Uvicorn is an ASGI container program -- it can run any ASGI-based Python web framework, like FastAPI, or recent versions of Django.
  • --app-dir /home/YOURUSERNAME/my_fastapi is the directory containing your website's code -- in this example, the FastAPI example.
  • --uds $DOMAIN_SOCKET is telling uvicorn to listen for incoming requests on a unix domain socket -- the location of that socket is provided by our system in the environment variable DOMAIN_SOCKET
  • main:app is telling uvicorn, which is looking for code in the specified app-dir, to load up the ASGI app called app from the file main.py. If you're using Django, it will be a little more complicated because of the way Django nests directories.

As we mentioned above, that domain socket (which will be something like /var/sockets/YOURUSERNAME.pythonanywhere.com/app.sock) is internal to the part of our system that serves websites; you won't be able to see it in a console or on the "Files" page inside PythonAnywhere.

If you want to use an ASGI framework that is not one of the ones we have examples for above, you should be able to get it up and running by:

  • Installing the framework into your virtualenv.
  • Adjusting the app-dir to point to the location of your code.
  • Changing the last argument to point to the ASGI object that your framework exports.

But in addition, you can even use our new website hosting system to host non-ASGI servers! It supports any server that is able to listen for incoming requests on a unix domain socket. You'll just need to work out the appropriate incantation to tell it how to listen on the socket provided in $DOMAIN_SOCKET.

The API

If you want to control your ASGI site programatically, using Python code rather than the pa command-line tool, check out this help page.