Applications

What are Applications?

Applications created via the dashboard are used to run your sites. An application can take many forms, such as a directory of static files, a PHP script (or several), or even a complex back-end server spawning several long-running processes.

You serve applications from your sites by assigning them to site routes. Please refer to Building A Site for more information.

Adding an Application

  1. Click Applications in the dashboard sidebar.

  2. Click the button "Add Application" at the top of the page. A form will appear.

  3. Select a shell user from the Shell User selection list, or use the "New Shell User" button to create one.

    Important

    Your site applications run as the shell user that owns them. This means that any application owned by a single shell user can potentially spawn proccesses to access or modify files and data for any other application belonging to that same shell user.

    For this reason, we very strongly recommend that you use a separate shell user for each website or project that you operate on your Opalstack account.

    Doing so will, for example, ensure that malware introduced via an outdated application cannot spread to the applications belonging to your other shell users.

  4. Select the desired application stack. Note that additional options may appear on the form after you've selected your application type.

  5. If you are adding a custom installer, click "My Custom Installers" to create or import your installer. See Custom Installers for more information.

  6. Configure the applicable options for the application stack that you've selected.

  7. Enter a name for the application. This will be the name of the directory on the server that will be created for your application.

  8. When all of the inputs are valid the button "Add Open App Stack" will appear on the form. Click the button to save your new application.

  9. The new application will appear in the application list with an initial status of "Starting". Some types of applications may take several minutes to create. When the installation is complete the status will change to "Ready".

  10. Check your dashboard notice log for additional details about your application such as your initial username and password (if applicable).

If a new application's status is not "Ready" following an installation then you can check for the cause of the failure in the application's install log. The log is located in the shell user's home directory at /home/shelluser/logs/apps/appname/install.log.

Viewing API Details for Applications

You can view the API details for your applications via your Opalstack dashboard.

  1. Click on Applications in the dashboard sidebar.

  2. Click the API icon (brackets) for the shell user in the upper section of the page. A window with the JSON API representation of the shell user will appear.

  3. When you are finished, click the "Close" button.

Modifying an Application

Some apps have parameters that can be modified via the dashboard after the app has been installed. To modify an app:

  1. Click on Applications in the dashboard sidebar.

  2. In the application list in the lower section of the page click the Edit icon (a pencil) in the rightmost column for the application that you want to modify. A form will appear.

  3. Adjust your app's parameters as needed.

  4. Click the green "Update Application" button to save your changes.

Deleting an Application

Important

Deleting an application will delete the related application directory and all of its contents.

  1. Click on Applications in the dashboard sidebar.

  2. Click the delete icon (a trash bin) for your application in the right edge of the application list.

  3. A confirmation prompt will appear. Click the red button to confirm the operation, or click the cancel button to cancel it.

  4. After you delete the application its status will update while the operation is pending, and the app will disappear a few seconds later when the operation is complete.

Application Logs

Most applications have log files that you can use for analysis and troubleshooting. The logs for each application are located in the application's shell user home directory under /home/shelluser/logs/apps/.

Application logs are kept for 7 days. Older logs are automatically deleted.

When an application is deleted, its logs are moved into /home/shelluser/logs/deleted/apps/.

Custom Installers

Custom installers are code snippets stored in your browser to allow quick installation of apps using your own custom installation scripts.

Note

Custom installers are stored in your browser as temporary data, not in the Opalstack control panel database. They are only available in the browser that you create them in.

Adding a custom installer

To add a custom installer:

  1. Follow steps 1 through 3 for adding an application.

  2. Select "Custom Installer URL" as the stack.

  3. Enter the URL to your custom installer script in the field labeled "Installer Script URL".

  4. Select the base application type for the app. For example, if your installer script installs an app that runs on a backend server listening on a port, then you would select "CUS - Proxied Port" as the application type.

  5. Click "Save as Reusable Installer".

  6. Enter a name for the installer. This will appear in the stack list when creating a new application.

  7. Enter a 3-character badge for the installer. This will appear next to the installer name in the stack list.

  8. Enter a short description of the installer.

  9. Click "Save to My Installers" to save the new installer. The installer will be saved in your browser's local storage and will automatically appear when adding apps via the control panel in that same browser.

  10. Optional: if you would like to share your new installer, click "Get Shareable Link" and copy the provided link.

Adding a custom installer as JSON

To add a custom installer as JSON:

  1. Follow steps 1 through 3 for adding an application.

  2. Scroll down to "My Custom Installers" on the form and click it.

  3. Paste your installer JSON into the space provided. The form includes a template that you can use to start with.

    The parameters are:

    • selected_type: a unique value identifying your installer, consisting of lowercase letters, underscores, and digits
    • name: the name of the installer that will appear on the form
    • badge: a 2-3 letter code displayed with your installer in the installer list
    • tagline: a short description of your installer
    • color: a CSS class defining the color of the isntalelr in the installer list
    • notes: a longer description of your installer
    • github: the homepage for your installer. This could be a Github repo or any other URL.
    • url > el7: the URL of your installation script when run on CentOS 7 servers.
    • url > el9: the URL of your installation script when run on AlmaLinux 9 servers.
    • app_type: the base application type used by your installer:
      • STA: Static Only
      • NPF: Nginx/PHP-FPM
      • APA: Apache/PHP-FPM
      • CUS: Custom Proxied Port
      • SLS: Symbolic link to Static only
      • SLP: Symbolic link to Apache/PHP-FPM
      • SLN: Symbolic link to Nginx/PHP-FPM

  4. Click "Add Installer" on the form to save the new installer. The installer will be saved in your browser's local storage and will automatically appear when adding apps via the control panel in that same browser.

Deleting a custom installer

To add a custom installer:

  1. Follow steps 1 through 3 for adding an application.

  2. Scroll down to "My Custom Installers" on the form and click it.

  3. Locate your installer in the installer list below the "Add Installer" button.

  4. Click the red X in the row for your installer. The installer will be immediately deleted.

Exporting your custom installers

To export your custom installers:

  1. Follow steps 1 through 3 for adding an application.

  2. Scroll down to "My Custom Installers" on the form and click it.

  3. Click the "Export All" link. Your installers' JSON will be displayed.

  4. Copy and paste the JSON into a file and save it.

Importing custom installers

To import custom installers:

  1. Follow steps 1 through 3 for adding an application.

  2. Scroll down to "My Custom Installers" on the form and click it.

  3. Click the "Import File" button.

  4. Select the JSON file containing the installers you want to import. This file must be in the same format as exported installers.

  5. The installers contained in the file will be imported into your custom installer list.

Creating your own installation scripts

Installation scripts are remotely-hosted scripts which perform the the steps to set up a new application, such as:

  • Downloading source code into the app directory
  • Creating a new database for the application to use
  • Writing configuration files with application-specific details like file paths, port assignment, etc.

When an installation script is used to install a new application from the control panel, the Opalstack system instruct the application's shell user to download the script and and then run it with a series of commands like the following: 

cd ~/apps/name_of_app; 
~/.osscrc/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX \
  -i XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX \
  -n name_of_app > ~/logs/apps/name_of_app/install.log

Here XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX is the UUID of the application assigned by the control panel and name_of_app is the app name that you specified when creating the app.

You can test your own installation script by first creating the base app with no options and then running that example command with the following replacements:

  • Replace name_of_app with the name of your base application.
  • Replace the -i paramater XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX with the UUID of your base application. You can get the UUID from the app's API Details.
  • Replace ~/.osscrc/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX with the path to your installation script. This doesn't have to include the UUID, the script name can be anything for testing.

Although we refer to them as "scripts", installation scripts can be any executable file. You can write your own installers as shell, Python, Javascript, Golang, Rust, or any other language you choose, provided that the installer meets a few requirements:

  • The script must be hosted on a public URL. This could be on a website hosted at Opalstack, a public Github repository, or any other web URL accessible without a username and password.
  • The URL must point to the actual file - for example, if you're hosting the script in a Github repository then the URL must point to the "raw" version of the script.
  • The script must be able to accept 2 command-line arguments:
    • i: the UUID of the application
    • s: the name of the application

Many example scripts are available in Opalstack's installer repository.