Starter apps

source/tutorials/tutorials-passenger-apps.rst

@@ -12,3 +12,5 @@ At the bottom of the page is a list of tutorials for developing Passenger apps f
    :caption: Tutorials
 
    tutorials-passenger-apps/ps-to-quota
+   tutorials-passenger-apps/nodejs-starter-app
+   tutorials-passenger-apps/python-starter-app

source/tutorials/tutorials-passenger-apps/nodejs-starter-app.rst

@@ -0,0 +1,95 @@
+.. _app-development-tutorials-node-js:
+
+Starter NodeJS Application
+==========================
+
+This document describes how to start a Passenger application
+in `NodeJs`_ language.
+
+
+Initialize the application
+--------------------------
+
+In this example we're going to initialize an application called ``nodejs-hello-world``.
+You may want to rename this directory to something more appropriate.
+
+.. code:: shell
+
+  cd ~/ondemand/dev
+  mkdir nodejs-hello-world
+  cd nodejs-hello-world
+  npm init
+
+.. warning::
+  ``npm init`` will initialize the ``main`` script as ``index.js``.  For OnDemand to recognzie
+  this application, the ``main`` attribute in ``package.json`` should be ``app.js`` not
+  ``index.js``.
+
+Add Web Framework
+-----------------
+
+First we need to add `Express`_ web framework.  Like all web frameworks, this
+library will route requests to the appropriate pages.
+
+Issue these commands to add and install the package.
+
+.. code:: shell
+
+  npm add express
+  npm install
+
+.. tip::
+
+  While this example uses `Express`_, you can choose any `NodeJs`_ web framework
+  available.
+
+Add and edit app.js
+-------------------
+
+Now we need the ``app.js`` file that's the entrypoint for this application.
+After creating this file, we've provided this starter content for you add
+to the file.
+
+This ``app.js`` imports the `Express`_ framework and sets up the ``router``
+to route requests to the functions that can serve that request. This starter
+file only has one route to the root url ``/`` and returns a simple ``Hello World``
+string.
+
+.. code:: javascript
+
+  // app.js
+
+  const express = require('express');
+  const app = express();
+  const port = 3000;
+
+  // have to use a Router to mount the `PASSENGER_BASE_URI`
+  // base uri that's /pun/dev/appname or /pun/sys/appname depending
+  // on the environment.
+  const router = express.Router();
+  app.use(process.env.PASSENGER_BASE_URI || '/', router);
+
+  router.get('/', (req, res) => {
+    res.send('Hello World!');
+  })
+
+  app.listen(port, () => {
+    console.log(`Example app listening on port ${port}`);
+  })
+
+
+Boot the application
+--------------------
+
+Now that the app's all setup and implemented, you should be able to
+boot it up.  To do so, simply navigate to ``My Sandbox Apps (Development)``
+in the ``Develop`` menu of your OnDemand installation.
+
+There you should see this application at the top of the list.  Clicking
+``Launch Nodejs Hello World`` will launch this application in a new tab.
+
+When the new tab opens you should see a blank page with the text ``Hello World``.
+This is your new `NodeJs`_ application!
+
+.. _NodeJs: https://nodejs.org/en
+.. _Express: https://expressjs.com/

source/tutorials/tutorials-passenger-apps/python-starter-app.rst

@@ -0,0 +1,142 @@
+.. _app-development-tutorials-python:
+
+Starter Python Application
+==========================
+
+
+This document describes how to start a Passenger application
+in `Python`_ language.
+
+Basic application
+-----------------
+
+``passenger_wsgi.py`` is the entrypoint for any python application.
+
+.. code:: shell
+
+  cd ~/ondemand/dev
+  mkdir python-hello-world
+  cd python-hello-world
+  touch passenger_wsgi.py
+
+Now with the ``passenger_wsgi.py`` file created, we can add this content to
+serve a response to a request.
+
+.. code:: python
+
+  # passenger_wsgi.py 
+  import sys
+
+  def application(environ, start_response):
+      start_response('200 OK', [('Content-type', 'text/plain')])
+      return ["Hello World from Open OnDemand (Python WSGI)!\n\n" + sys.version]
+
+Boot the application
+--------------------
+
+Now that the app's all setup and implemented, you should be able to
+boot it up.  To do so, simply navigate to ``My Sandbox Apps (Development)``
+in the ``Develop`` menu of your OnDemand installation.
+
+There you should see this application at the top of the list.  Clicking
+``Launch Python Hello World`` will launch this application in a new tab.
+
+When the new tab opens you should see a blank page with the text ``Hello World``
+with some extra text about the system. This is your new `Python`_ application!
+
+
+Application using Flask and a virtual environment
+-------------------------------------------------
+
+The basic application above is fine, but you'll likely need to add
+more dependencies and load those dependencies at runtime.
+
+So this section goes over adding the `Flask`_ web framework and having
+the application load the virtual environment that has your dependencies in
+it.
+
+Create the virtual environmet
+`````````````````````````````
+
+First, we need to create the virtual environment. Issue this command below
+to create one. This will create a subdirectory ``python-hello-world`` with a
+``bin/activate`` file you can use to activate the environment.
+
+.. code:: shell
+
+  python3 -m venv python-hello-world
+
+Now, let's create the ``requriements.txt`` file where we'll add the application's
+required libraries. Here, we're only adding ``flask`` of any version.
+
+.. code:: text
+
+  # requirements.txt
+  flask
+
+.. code:: shell
+
+  source python-hello-world/bin/activate
+  python3 -m pip install -r requirements.txt
+
+Create the python files
+```````````````````````
+
+In the basic example above, the entire implementation is held within a ``passenger_wsgi.py``.
+This project is more advanced, so it will include two files. ``passenger_wsgi.py`` and
+``app.py``.  ``app.py`` will hold the logic for the application.
+
+``passenger_wsgi.py`` simply imports the app from the ``app.py`` file. This is all that's required
+for this file.
+
+.. code:: python
+
+  # passenger_wsgi.py
+  from app import MyApp as application
+
+``app.py`` on the other hand, has logic associcated with the web application in it.
+It imports the `Flask`_ libraries, configures the routes and starts the flask server.
+
+.. code:: python
+
+  # app.py
+  from flask import Flask
+  import sys
+
+  MyApp = Flask('python_hello_world')
+
+  @MyApp.route("/")
+  def index():
+    return 'Hello World!<br>' + sys.version
+
+  if __name__ == "__main__":
+    MyApp.run()
+
+Using the virtual environment
+`````````````````````````````
+
+At this point, the app is basically done, but won't boot up because it
+can't find `Flask`_ libraries. We created a virtual environment in a previous
+step, now we have to get OnDemand to recognize this environment.
+
+To do this, we need to create a `bin/python` wrapper file to load the appropriate
+virtual environment.
+
+.. code:: shell
+
+  #!/usr/bin/env bash
+
+  SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+  source $SCRIPT_DIR/../python-hello-world/bin/activate
+
+  exec /bin/env python3 "$@"
+
+.. warning::
+  Ensure that this ``bin/python`` file has executable permissons on it.
+  Issue the command ``chmod +x bin.python`` to give it executable permissions.
+
+Now, with the python wrapper script to load the environment for your application,
+it should boot up correctly.
+
+.. _Python: https://www.python.org/
+.. _Flask: https://flask.palletsprojects.com/en/3.0.x/