Merge branch 'main' into jlink-plugin

docs/.wordlist.txt

@@ -1,5 +1,6 @@
 ACR
 ARGS
+ASGI
 Autotools
 autotools
 boolean
@@ -31,6 +32,8 @@ entrypoint
 entrypoints
 executables
 expressjs
+fastapi
+FastAPI
 Filesets
 fileset
 filesets
@@ -138,6 +141,7 @@ ubuntu
 unbuilt
 UID
 usrmerge
+Uvicorn
 VENV
 venv
 WSGI

docs/reference/extensions/fastapi-framework.rst

@@ -0,0 +1,58 @@
+.. _fastapi-framework-reference:
+
+fastapi-framework
+-----------------
+
+The FastAPI extension streamlines the process of building FastAPI application
+rocks.
+
+It facilitates the installation of FastAPI application dependencies, including
+Uvicorn, inside the rock. Additionally, it transfers your project files to
+``/app`` within the rock.
+
+.. note::
+    The FastAPI extension is compatible with the ``bare`` and ``ubuntu@24.04``
+    bases.
+
+Project requirements
+====================
+
+There are 2 requirements to be able to use the ``fastapi-framework`` extension:
+
+1. There must be a ``requirements.txt`` file in the root of the project with
+   ``fastapi`` declared as a dependency
+2. The project must include a ASGI app in a variable called ``app`` in one of
+   the following files relative to the project root (in order of priority):
+
+   * ``app.py``
+   * ``main.py``
+   * ``__init__.py``, ``app.py`` or ``main.py`` within the ``app`` or ``src``
+     directory or within a directory with the name of the rock as declared in
+     ``rockcraft.yaml``.
+
+``parts`` > ``fastapi-framework/install-app`` > ``prime``
+=========================================================
+
+You can use this field to specify the files to be included or excluded from
+your rock upon ``rockcraft pack``. Follow the ``app/<filename>`` notation. For
+example:
+
+.. code-block:: yaml
+
+  parts:
+    fastapi-framework/install-app:
+      prime:
+        - app/.env
+        - app/app.py
+        - app/webapp
+        - app/templates
+        - app/static
+
+Some files, if they exist, are included by default. These include:
+``app``, ``src``, ``<rock name>``, ``app.py``, ``migrate``, ``migrate.sh``,
+``migrate.py``, ``static``, ``templates``.
+
+Useful links
+============
+
+- :ref:`build-a-rock-for-a-fastapi-application`

docs/reference/extensions/index.rst

@@ -13,3 +13,4 @@ initiating a new rock.
 
    flask-framework
    django-framework
+   fastapi-framework

docs/reference/rockcraft.yaml.rst

@@ -263,6 +263,9 @@ Extensions to enable when building the ROCK.
 Currently supported extensions:
 
 - ``flask-framework``
+- ``django-framework``
+- ``go-framework``
+- ``fastapi-framework``
 
 Example
 =======

docs/tutorial/code/django/task.yaml

@@ -23,7 +23,7 @@ execute: |
 
   cd django_hello_world
   python manage.py runserver &
-  retry -n 5 --wait 2 curl localhost:8000
+  retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-django]
   curl localhost:8000
@@ -59,7 +59,7 @@ execute: |
   sudo docker run --rm -d -p 8000:8000 \
     --name django-hello-world django-hello-world:0.1
   # [docs:docker-run-end]
-  retry -n 5 --wait 2 curl localhost:8000
+  retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-django-rock]
   curl localhost:8000
@@ -97,7 +97,7 @@ execute: |
   sudo docker run --rm -d -p 8000:8000 \
     --name django-hello-world django-hello-world:0.1-chiselled
   # [docs:docker-run-chisel-end]
-  retry -n 5 --wait 2 curl localhost:8000
+  retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-django-bare-rock]
   curl localhost:8000
@@ -128,7 +128,7 @@ execute: |
   sudo docker run --rm -d -p 8000:8000 \
     --name django-hello-world django-hello-world:0.2
   # [docs:docker-run-update-end]
-  retry -n 5 --wait 2 curl localhost:8000/time/
+  retry -n 5 --wait 2 curl --fail localhost:8000/time/
 
   # [docs:curl-time]
   curl localhost:8000/time/
@@ -142,7 +142,7 @@ execute: |
   # [docs:cleanup]
   # exit and delete the virtual environment
   deactivate
-  rm -rf .venv django_hello_world
+  rm -rf .venv django_hello_world __pycache__
   # delete all the files created during the tutorial
   rm django-hello-world_0.1_amd64.rock \
     django-hello-world_0.1-chiselled_amd64.rock \

docs/tutorial/code/fastapi/app.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}

docs/tutorial/code/fastapi/requirements.txt

@@ -0,0 +1 @@
+fastapi[standard]

docs/tutorial/code/fastapi/task.yaml

@@ -0,0 +1,137 @@
+###########################################
+# IMPORTANT
+# Comments matter!
+# The docs use the wrapping comments as 
+# markers for including said instructions 
+# as snippets in the docs.
+###########################################
+summary: Getting started with FastAPI tutorial
+
+environment:
+
+execute: |
+  # [docs:create-venv]
+  sudo apt-get update && sudo apt-get install python3-venv -y
+  python3 -m venv .venv
+  source .venv/bin/activate
+  pip install -r requirements.txt
+  # [docs:create-venv-end]
+
+  fastapi dev app.py --port 8000 &
+  retry -n 5 --wait 2 curl --fail localhost:8000
+
+  # [docs:curl-fastapi]
+  curl localhost:8000
+  # [docs:curl-fastapi-end]
+
+  kill $!
+
+  # [docs:create-rockcraft-yaml]
+  rockcraft init --profile fastapi-framework
+  # [docs:create-rockcraft-yaml-end]
+  sed -i "s/name: .*/name: fastapi-hello-world/g" rockcraft.yaml
+
+  # [docs:pack]
+  ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true rockcraft pack
+  # [docs:pack-end]
+
+  # [docs:ls-rock]
+  ls *.rock -l --block-size=MB
+  # [docs:ls-rock-end]
+
+  # [docs:skopeo-copy]
+  sudo rockcraft.skopeo --insecure-policy \
+    copy oci-archive:fastapi-hello-world_0.1_amd64.rock \
+    docker-daemon:fastapi-hello-world:0.1
+  # [docs:skopeo-copy-end]
+
+  # [docs:docker-images]
+  sudo docker images fastapi-hello-world:0.1
+  # [docs:docker-images-end]
+
+  # [docs:docker-run]
+  sudo docker run --rm -d -p 8000:8000 \
+    --name fastapi-hello-world fastapi-hello-world:0.1
+  # [docs:docker-run-end]
+  retry -n 5 --wait 2 curl --fail localhost:8000
+
+  # [docs:curl-fastapi-rock]
+  curl localhost:8000
+  # [docs:curl-fastapi-rock-end]
+
+  # [docs:get-logs]
+  sudo docker exec fastapi-hello-world pebble logs fastapi
+  # [docs:get-logs-end]
+
+  # [docs:stop-docker]
+  sudo docker stop fastapi-hello-world
+  sudo docker rmi fastapi-hello-world:0.1
+  # [docs:stop-docker-end]
+
+  # [docs:change-base]
+  sed -i \
+    "s/base: .*/base: bare\nbuild-base: ubuntu@24.04/g" \
+    rockcraft.yaml
+  # [docs:change-base-end]
+  sed -i "s/version: .*/version: 0.1-chiselled/g" rockcraft.yaml
+
+  # [docs:chisel-pack]
+  ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true rockcraft pack
+  # [docs:chisel-pack-end]
+
+  # [docs:ls-bare-rock]
+  ls *.rock -l --block-size=MB
+  # [docs:ls-bare-rock-end]
+
+  # [docs:docker-run-chisel]
+  sudo rockcraft.skopeo --insecure-policy \
+    copy oci-archive:fastapi-hello-world_0.1-chiselled_amd64.rock \
+    docker-daemon:fastapi-hello-world:0.1-chiselled
+  sudo docker images fastapi-hello-world:0.1-chiselled
+  sudo docker run --rm -d -p 8000:8000 \
+    --name fastapi-hello-world fastapi-hello-world:0.1-chiselled
+  # [docs:docker-run-chisel-end]
+  retry -n 5 --wait 2 curl --fail localhost:8000
+
+  # [docs:curl-fastapi-bare-rock]
+  curl localhost:8000
+  # [docs:curl-fastapi-bare-rock-end]
+
+  # [docs:stop-docker-chisel]
+  sudo docker stop fastapi-hello-world
+  sudo docker rmi fastapi-hello-world:0.1-chiselled
+  # [docs:stop-docker-chisel-end]
+
+  cat time_app.py > app.py
+  sed -i "s/version: .*/version: 0.2/g" rockcraft.yaml
+
+  # [docs:docker-run-update]
+  ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true rockcraft pack
+  sudo rockcraft.skopeo --insecure-policy \
+    copy oci-archive:fastapi-hello-world_0.2_amd64.rock \
+    docker-daemon:fastapi-hello-world:0.2
+  sudo docker images fastapi-hello-world:0.2
+  sudo docker run --rm -d -p 8000:8000 \
+    --name fastapi-hello-world fastapi-hello-world:0.2
+  # [docs:docker-run-update-end]
+  retry -n 5 --wait 2 curl --fail localhost:8000/time
+
+  # [docs:curl-time]
+  curl localhost:8000/time
+  # [docs:curl-time-end]
+
+  # [docs:stop-docker-updated]
+  sudo docker stop fastapi-hello-world
+  sudo docker rmi fastapi-hello-world:0.2
+  # [docs:stop-docker-updated-end]
+
+  # [docs:cleanup]
+  # exit and delete the virtual environment
+  deactivate
+  rm -rf .venv __pycache__
+  # delete all the files created during the tutorial
+  rm fastapi-hello-world_0.1_amd64.rock \
+    fastapi-hello-world_0.1-chiselled_amd64.rock \
+    fastapi-hello-world_0.2_amd64.rock \
+    rockcraft.yaml app.py requirements.txt
+  # [docs:cleanup-end]

docs/tutorial/code/fastapi/time_app.py

@@ -0,0 +1,15 @@
+import datetime
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+
+
+@app.get("/time")
+def time():
+    return {"value": f"{datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"}

docs/tutorial/code/flask/task.yaml

@@ -18,7 +18,7 @@ execute: |
   # [docs:create-venv-end]
 
   flask run -p 8000 &
-  retry -n 5 --wait 2 curl localhost:8000
+  retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-flask]
   curl localhost:8000
@@ -53,7 +53,7 @@ execute: |
   sudo docker run --rm -d -p 8000:8000 \
     --name flask-hello-world flask-hello-world:0.1
   # [docs:docker-run-end]
-  retry -n 5 --wait 2 curl localhost:8000
+  retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-flask-rock]
   curl localhost:8000
@@ -91,7 +91,7 @@ execute: |
   sudo docker run --rm -d -p 8000:8000 \
     --name flask-hello-world flask-hello-world:0.1-chiselled
   # [docs:docker-run-chisel-end]
-  retry -n 5 --wait 2 curl localhost:8000
+  retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-flask-bare-rock]
   curl localhost:8000
@@ -115,7 +115,7 @@ execute: |
   sudo docker run --rm -d -p 8000:8000 \
     --name flask-hello-world flask-hello-world:0.2
   # [docs:docker-run-update-end]
-  retry -n 5 --wait 2 curl localhost:8000/time
+  retry -n 5 --wait 2 curl --fail localhost:8000/time
 
   # [docs:curl-time]
   curl localhost:8000/time
@@ -129,7 +129,7 @@ execute: |
   # [docs:cleanup]
   # exit and delete the virtual environment
   deactivate
-  rm -rf .venv
+  rm -rf .venv __pycache__
   # delete all the files created during the tutorial
   rm flask-hello-world_0.1_amd64.rock \
     flask-hello-world_0.1-chiselled_amd64.rock \

docs/tutorial/django.rst

@@ -305,8 +305,8 @@ image:
 
 .. _update-django-application:
 
-Update Django application
-=========================
+Update the Django application
+=============================
 
 As a final step, let's update our application. For example,
 we want to add a new ``/time/`` endpoint which returns the current time.