diff --git a/source/tutorials/tutorials-passenger-apps.rst b/source/tutorials/tutorials-passenger-apps.rst index 0c6266f6..2bb8d1a5 100644 --- a/source/tutorials/tutorials-passenger-apps.rst +++ b/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 \ No newline at end of file diff --git a/source/tutorials/tutorials-passenger-apps/nodejs-starter-app.rst b/source/tutorials/tutorials-passenger-apps/nodejs-starter-app.rst new file mode 100644 index 00000000..f6ea4c40 --- /dev/null +++ b/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/ diff --git a/source/tutorials/tutorials-passenger-apps/python-starter-app.rst b/source/tutorials/tutorials-passenger-apps/python-starter-app.rst new file mode 100644 index 00000000..909fa5e4 --- /dev/null +++ b/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!
' + 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/