.. _custom-apps: Running any app with shell scripts ================================== Besides using :ref:`Plotly Dash ` and :ref:`R Shiny `, Faculty supports building custom applications that are run from a given shell script. It is the most flexible way of running apps, as you can start any kind of server from a shell script. .. contents:: Contents :local: .. _developing_custom_apps: Developing the application -------------------------- When you are just starting out, you probably want to develop the application without exposing it to other people in your project. The easiest way of doing this is to just create a Jupyter server, open a terminal in that server and run the following commands: .. code-block:: bash $ conda activate Python3 $ sudo sv stop jupyter This has stopped the Jupyter notebook running on that instance, freeing the port for our application. Let's start by creating a directory in the project workspace: .. code-block:: bash $ mkdir -p /project/custom-app-example Let's now write the code for our application. We will create an application that hosts static website content. Create a file called ``app.sh`` in ``/project/custom-app-example``, with the following contents: .. code-block:: shell exec python -m http.server 8888 This code defines a minimal application that listens on port 8888, the port that we have freed by stopping Jupyter. Let's also create another file, called ``index.html`` in ``/project/custom-app-example``, with the following contents: .. code-block:: html My First Custom App This is a very simple static website that we can display. Let's now start our app: .. code-block:: bash $ cd /project/custom-app-example $ bash app.sh If you now open your server from the servers section of the workspace: .. image:: images/open_server.png :width: 50% :align: center You will see your application! .. image:: images/custom_app_example.png Carry on developing your app. Deploying the application ------------------------- You have now developed a great app, and you want to let other members of your project access it. Head to the `Deployments` page in Faculty, and in the `Apps` tab click the `+` button above the tab to create a new app. You will be prompted to enter a name and domain for your app. Select `Custom` for `Type`. .. image:: images/new_app_modal_custom.png Click `Create App`. You will then be taken to the `App Settings` page. You will need to make the following changes to the application settings: - Change the `working directory` to ``/project/custom-app-example``. - Change the `script` to ``app.sh``. .. thumbnail:: images/custom_app_settings.png Save your application by clicking the `Save` button, then click `Start app` to start your custom app server. After a few seconds, you will see the status of your app change to `Running`. At this point, a URL will appear. Select that URL and place it in your browser search bar. You will be taken to the application! Behind the scenes, Faculty verifies that you are at least an observer in the project that the app belongs to. While your app is deployed, you can monitor its logs in the `Monitor` tab. Sharing your application ------------------------ To share the application with a team member who is an observer in the project, just give them the URL of the application! To invite people to your project, go to the `Collaborators` page, enter their Faculty username or the email that they used to sign up to Faculty, and assign them observer status. .. thumbnail:: images/team_page_with_observer.png