Skip to content

Enable app installation from the Dashboard

here are some Figma wireframes. Unfortunately they don't include the actual app installation. They also include some stuff we don't need at the moment:

  • App multi-select is not needed
  • Configure app general:
    • Needed:
      • Disable app
      • View documentation
      • Automatic updates (under General tab)
      • Advanced configuration
        • Version management is a nice-to-have
    • Not needed:
      • "Privacy" (under General tab)
      • "Notifications" (under General tab)
      • "Add a new app" button: I propose a different solution in "Installing Apps" below.
    • Nice to have:
      • Per-app access management (we already have per-user access management)
        • less important: default access to app for new users

Some features need to exist, but are not specified in the wireframe:

  • Install app

User journey specification

Admin user

Installing apps

Starting state: Just installed Stackspin, 0 apps have been installed. Admin user has just logged in for the first time.

As a Dashboard Admin user, when I click the "Apps" tab, I see a "apps overview screen" with a table showing all the available apps. The table looks like in wireframe "Apps - Hover configure". All the apps have status "Not installed".

When I hover over an app in the table, a button named "Install" pops up.

When I click the "Install" button for an app, a modal pops up. The model allows me to:

  1. Specify the (sub)domain for the app. The (sub)domain field is pre-filled with the default subdomain1. The modal has a "Cancel" and an "Install..." button at the bottom. When I click the "Install" button, the modal closes and I'll see the "apps overview screen" again. The status of the installing app is now "Installing...".

  2. Set advanced configuration in an optional tab or collapsed section.

I can click the status to get more information. Not sure yet what it would show, but I'm thinking:

  • easy: A notification saying "Installing an app can take up to 10 minutes"
  • harder: The current Kustomization and HelmRelease status? (although this could also confuse people)
  • hardest: The possibility to view logs
    • We'd have to have a selector for which pod's logs we want to show. Or maybe use Loki to get a combination of all the application's pods' logs.

Once the application has finished installing its status in the table changes to "Running"

Changing app configuration

Starting state: On the "app overview screen", (at least) one app is installed. The installed app is referred to as "the app" in this section.

I click the "Configure..." button for the app. The "app configuration" screen (like "Configure App - General" in the Figma, but without the features mentioned above as "not needed") opens.

I click "Advanced configuration". The "Advanced configuration" screen opens (in Figma: Configure App - Advanced Configuration)

I see the current configuration on the left side, under "Current configuration". The "Edit configuration" text area (right side) shows me the current configuration as well. I can edit the Edit Configuration text area, but I cannot edit the "Current Configuration" text area.

Version history is a nice-to-have.

If I click "Verify", a verification script runs. This will:

  • easy: verify that I have entered valid Yaml
  • hard: verify that I have entered valid data for this specific app configuration (nice-to-have. If we know how to do it, we can add it to the verification webhook later).

If the verification fails, I see an error mesagge.

If the vefirication succeeds, I see a success message (maybe the "verify" button contains a tickmark or changes colour? If we do that, we should make sure to undo this if I edit the configuration again)

When I click the "save" button:

  1. Verification runs again.
    • If verification fails, the same happens as when I would have clicked the "Verify" button
  2. If verification succeeds, the configuration changes are saved

Once the configuration changes are saved, my app gets "reconciled" (this is a Flux term). I get redirected to the "app overview screen" The status of my app changes to "reconciling" until the configuration has been applied.

If I click the status, I get:

  • easy: A notification saying "Reconciling an app can take up to 10 minutes"
  • harder: The current Kustomization and HelmRelease status? (although this could also confuse people)
  • hardest: The possibility to view logs
    • We'd have to have a selector for which pod's logs we want to show. Or maybe use Loki to get a combination of all the application's pods' logs.

Once reconciliation has finished, the app status in the table changes to "Running".

Viewing documentation

All apps have a button that links to the app's documentation. This button is visible on:

  • The "App configuration screen"
  • The "Dashboard" tab

The button is for app users, so I propose to change the name from "Documentation" to "View manual". Because the button is on the Dashboard tab, users as well as admins can click it. It points to the app's user manual:

App multi-select

This feature (Figma: Apps - Select) does not seem very useful to me and does not have to be implemented

Disable App

Starting state: I have at least 1 app installed and I'm on that app's "app configuration screen".

When I click the "Disable app" button, I get an "Are you sure?" modal that says:

Disable App

Are you sure you want to disable {{ app_name }}? The app will get uninstalled and none of your users will be able to access the app.

  • Remove app data

    • If unchecked, show message: "The app's data does not get removed. If you install the app again, you will be able to access the data again."
    • If checked, show message: "The app's data will be removed. After this operation is done you will not be able to access the app, nor the app data. If you re-install the app, it will have none of the data it had before."
  • There is a button "No, cancel". If pressed the modal closes, nothing happens
  • There is a button "Yes, delete "
    • If the "Remove app data" was checked, the button says "Yes, delete and its data"

Non-admin user

As a non-Admin dashboard user, I don't see the "Apps" tab. I can't install, remove or configure apps.

Dashboard

Ignore the Figma version of the dashboard. Instead take a look at As a non-admin dashboard user, I only see the applications in the "Dashboard" that:

  • Are installed, and
  • I have User or Admin access to

If I click "Go to app", I get directed to the app If I click "User manual", I go to the user manual of the app (links mentioned above, in admin section).

Technical specification

To Do

To be done after I get the OK about the user specification.

  1. Default subdomains: Nextcloud = files.{domain}, Zulip = zulip.{domain}, WordPress = www.{domain}, Wekan = wekan.{domain}. ↩

Edited by Maarten de Waard
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information