feat: expressjs framework

docs/how-to/extensions/configure-the-build-base-for-expressjs-app.rst

@@ -0,0 +1,86 @@
+.. _configure-the-build-base-for-expressjs-app:
+
+expressjs-framework
+===================
+
+When using the ``expressjs-framework`` extension, there are four different cases
+for customising the Ubuntu base and the Node version to be included.
+The main differences between the cases are:
+
+- Whether to use the bare base or Ubuntu 24.04 base.
+- Whether Node is installed from Ubuntu package archive or the NPM plugin.
+
+The remainder of this page discusses the combinations of
+Ubuntu bases and sources for Node.js.
+
+Ubuntu 24.04 base, Node.js from Ubuntu package archive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+    :caption: rockcraft.yaml
+
+    base: ubuntu@24.04
+    extensions:
+        - expressjs-framework
+
+In this case, the application is installed and run via Node and NPM is installed
+from the Ubuntu package archive. The NPM and Node versions are determined by the
+versions of NPM and NodeJS shipped with the Ubuntu base. See the NodeJS version
+shipped with the corressponding Ubuntu base from the chilsel-slices repository.
+This `link to the slices repository
+<https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/
+nodejs.yaml>`_ is an example of the NodeJS version shipped with the Ubuntu 24.04
+base.
+
+Ubuntu 24.04 base, Node.js from NPM plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+    :caption: rockcraft.yaml
+
+    base: ubuntu@24.04
+    extensions:
+        - expressjs-framework
+    parts:
+        expressjs-framework/install-app:
+            npm-include-node: true
+            npm-node-version: 20.12
+
+In this case, the application is installed and run via NodeJS provided by the
+NPM plugin. The NPM is also installed by the NPM plugin.
+
+Bare base, and Node.js from Ubuntu package archive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+    :caption: rockcraft.yaml
+
+    base: bare
+    build-base: ubuntu@24.04
+
+In this case, the application is installed and run via Node and NPM is
+installed from the Ubuntu package archive. The NPM and Node versions are
+determined by the versions of NPM and NodeJS shipped with the Ubuntu base.
+See the NodeJS version shipped with
+the corressponding Ubuntu base from the chilsel-slices repository.
+See the NPM version shipped with the corressponding Ubuntu base from the Ubuntu
+packages archive from the `Ubuntu packages search <https://packages.ubuntu.com/\
+search?suite=default&section=all&arch=any&keywords=npm&searchon=names>`_.
+
+Bare base, Node.js from NPM plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+    :caption: rockcraft.yaml
+
+    base: bare
+    build-base: ubuntu@24.04
+    parts:
+        expressjs-framework/install-app:
+            npm-include-node: true
+            npm-node-version: 20.12
+
+In this case, the application is installed and run via NodeJS and NPM from the
+NPM plugin. For different possible inputs for npm-node-version, refer to
+the `NPM plugin documentation <https://documentation.ubuntu.com/rockcraft/en/\
+latest/common/craft-parts/reference/plugins/npm_plugin>`_.

docs/how-to/extensions/index.rst

@@ -0,0 +1,6 @@
+.. _how-to-extensions:
+
+.. toctree::
+   :maxdepth: 1
+
+   configure-the-build-base-for-expressjs-app

docs/how-to/index.rst

@@ -39,6 +39,17 @@ compiled a couple of guides for you to facilitate your contribution.
 
    documentation <documentation/index>
 
+Extensions
+----------
+
+Learn how to use and customize different Rockcraft extensionss in your
+rockcraft.yaml to best suit your use cases.
+
+.. toctree::
+   :maxdepth: 1
+
+   extensions <extensions/index>
+
 Rocks
 -----
 

docs/reference/extensions/expressjs-framework.rst

@@ -0,0 +1,55 @@
+.. _expressjs-framework-reference:
+
+expressjs-framework
+-------------------
+
+The ExpressJS extension streamlines the process of building ExpressJS
+application rocks.
+
+It facilitates the installation of ExpressJS application dependencies, including
+Node and NPM, inside the rock. Additionally, it transfers your project files to
+``/app`` within the rock.
+
+The ExpressJS extension is compatible with the ``bare`` and ``ubuntu@24.04``
+bases.
+
+Project requirements
+====================
+
+There are 3 requirements to be able to use the ``expressjs-framework``
+extension:
+
+1. The application should reside in the ``app`` directory.
+2. The application should have a ``package.json`` file.
+3. The ``package.json`` file should define the ``start`` script.
+
+
+``parts`` > ``expressjs-framework/install-app`` > ``npm-include-node``
+======================================================================
+
+You can use this field to specify the version of Node to be installed. For
+example:
+
+.. code-block:: yaml
+
+  parts:
+    expressjs-framework/install-app:
+      npm-include-node: true
+      npm-node-version: 20.12.2
+
+For more examples of the ``npm-node-version`` key, see the
+`NPM plugin <httpshttps://documentation.ubuntu.com/rockcraft/en/latest/common/
+craft-parts/reference/plugins/npm_plugin/#examples>`_ documentation.
+
+If you don't customise the version of node, it will be installed from the Ubuntu
+package repository.
+
+``parts`` > ``expressjs-framework/runtime:`` > ``stage-packages``
+=================================================================
+
+Installing additional runtime packages is currently unsupported.
+
+See also
+========
+
+- :ref:`build-a-rock-for-an-expressjs-application`

docs/reference/extensions/index.rst

@@ -15,3 +15,4 @@ initiating a new rock.
    django-framework
    fastapi-framework
    go-framework
+   expressjs-framework

docs/reference/rockcraft.yaml.rst

@@ -266,6 +266,7 @@ Currently supported extensions:
 - ``django-framework``
 - ``go-framework``
 - ``fastapi-framework``
+- ``expressjs-framework``
 
 Example
 =======

docs/tutorial/code/django/task.yaml

@@ -26,7 +26,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-django]
-  curl localhost:8000
+  curl --fail localhost:8000
   # [docs:curl-django-end]
 
   kill $!
@@ -62,7 +62,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-django-rock]
-  curl localhost:8000
+  curl --fail localhost:8000
   # [docs:curl-django-rock-end]
 
   # [docs:get-logs]
@@ -100,7 +100,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-django-bare-rock]
-  curl localhost:8000
+  curl --fail localhost:8000
   # [docs:curl-django-bare-rock-end]
 
   # [docs:stop-docker-chisel]
@@ -131,7 +131,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000/time/
 
   # [docs:curl-time]
-  curl localhost:8000/time/
+  curl --fail localhost:8000/time/
   # [docs:curl-time-end]
 
   # [docs:stop-docker-updated]

docs/tutorial/code/expressjs/task.yaml

@@ -0,0 +1,117 @@
+###########################################
+# IMPORTANT
+# Comments matter!
+# The docs use the wrapping comments as
+# markers for including said instructions
+# as snippets in the docs.
+###########################################
+summary: Getting started with ExpressJS tutorial
+
+environment:
+
+execute: |
+  # [docs:install-deps]
+  sudo apt-get update -y && sudo apt-get install npm -y
+  # [docs:install-deps-end]
+
+  # [docs:init-app]
+  sudo npm install -g express-generator@4
+  express app
+  cd app && npm install
+  # [docs:init-app-end]
+
+  npm start &
+  cd ..
+  retry -n 5 --wait 2 curl --fail localhost:3000
+
+  # [docs:curl-expressjs]
+  curl --fail localhost:3000
+  # [docs:curl-expressjs-end]
+
+  kill $!
+  kill $(lsof -t -i:3000)
+
+  # [docs:create-rockcraft-yaml]
+  rockcraft init --profile expressjs-framework
+  # [docs:create-rockcraft-yaml-end]
+
+  sed -i "s/name: .*/name: expressjs-hello-world/g" rockcraft.yaml
+
+  # [docs:experimental]
+  export ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true
+  # [docs:experimental-end]
+
+  # [docs:pack]
+  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:expressjs-hello-world_0.1_amd64.rock \
+    docker-daemon:expressjs-hello-world:0.1
+  # [docs:skopeo-copy-end]
+
+  # [docs:docker-images]
+  sudo docker images expressjs-hello-world:0.1
+  # [docs:docker-images-end]
+
+  # [docs:docker-run]
+  sudo docker run --rm -d -p 3000:3000 \
+    --name expressjs-hello-world expressjs-hello-world:0.1
+  # [docs:docker-run-end]
+  retry -n 5 --wait 2 curl --fail localhost:3000
+
+  # [docs:curl-expressjs-rock]
+  curl --fail localhost:3000
+  # [docs:curl-expressjs-rock-end]
+
+  # [docs:get-logs]
+  sudo docker exec expressjs-hello-world pebble logs expressjs
+  # [docs:get-logs-end]
+
+  # [docs:stop-docker]
+  sudo docker stop expressjs-hello-world
+  sudo docker rmi expressjs-hello-world:0.1
+  # [docs:stop-docker-end]
+
+  mv time.js app/routes/
+  original_line="var app = express();"
+  # Remove comments from time_app.js
+  sed -i 's:^//.*::g' time_app.js
+  append_line="$(cat time_app.js | tr '\n' ' ')"
+  sed -i "/$original_line/a$append_line" app/app.js
+  sed -i "s/version: .*/version: 0.2/g" rockcraft.yaml
+
+  # [docs:docker-run-update]
+  rockcraft pack
+  sudo rockcraft.skopeo --insecure-policy \
+    copy oci-archive:expressjs-hello-world_0.2_amd64.rock \
+    docker-daemon:expressjs-hello-world:0.2
+  sudo docker images expressjs-hello-world:0.2
+  sudo docker run --rm -d -p 3000:3000 \
+    --name expressjs-hello-world expressjs-hello-world:0.2
+  # [docs:docker-run-update-end]
+  retry -n 5 --wait 2 curl --fail localhost:3000/time
+
+  # [docs:curl-time]
+  curl --fail localhost:3000/time
+  # [docs:curl-time-end]
+
+  # [docs:stop-docker-updated]
+  sudo docker stop expressjs-hello-world
+  sudo docker rmi expressjs-hello-world:0.2
+  # [docs:stop-docker-updated-end]
+
+  # [docs:cleanup]
+  # delete all the files created during the tutorial
+  npm uninstall -g express-generator@4
+  sudo apt-get remove npm -y
+  rm -rf app
+  rm expressjs-hello-world_0.1_amd64.rock \
+    expressjs-hello-world_0.2_amd64.rock \
+    rockcraft.yaml
+  # [docs:cleanup-end]

docs/tutorial/code/expressjs/time.js

@@ -0,0 +1,8 @@
+var express = require('express');
+var router = express.Router();
+
+router.get('/', function (req, res, next) {
+    res.send(Date());
+});
+
+module.exports = router;

docs/tutorial/code/expressjs/time_app.js

@@ -0,0 +1,4 @@
+// [docs:append-lines]
+var timeRouter = require('./routes/time');
+app.use('/time', timeRouter);
+// [docs:append-lines-end]

docs/tutorial/code/fastapi/task.yaml

@@ -1,8 +1,8 @@
 ###########################################
 # IMPORTANT
 # Comments matter!
-# The docs use the wrapping comments as 
-# markers for including said instructions 
+# The docs use the wrapping comments as
+# markers for including said instructions
 # as snippets in the docs.
 ###########################################
 summary: Getting started with FastAPI tutorial
@@ -21,7 +21,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-fastapi]
-  curl localhost:8000
+  curl --fail localhost:8000
   # [docs:curl-fastapi-end]
 
   kill $!
@@ -56,7 +56,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-fastapi-rock]
-  curl localhost:8000
+  curl --fail localhost:8000
   # [docs:curl-fastapi-rock-end]
 
   # [docs:get-logs]
@@ -94,7 +94,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000
 
   # [docs:curl-fastapi-bare-rock]
-  curl localhost:8000
+  curl --fail localhost:8000
   # [docs:curl-fastapi-bare-rock-end]
 
   # [docs:stop-docker-chisel]
@@ -117,7 +117,7 @@ execute: |
   retry -n 5 --wait 2 curl --fail localhost:8000/time
 
   # [docs:curl-time]
-  curl localhost:8000/time
+  curl --fail localhost:8000/time
   # [docs:curl-time-end]
 
   # [docs:stop-docker-updated]