Skip to content
Snippets Groups Projects
Commit 278fed3e authored by kbeyro's avatar kbeyro
Browse files

migrate user-guide

parent 70073ec8
Branches
No related tags found
No related merge requests found
Showing
with 188 additions and 0 deletions
docs/guides/img/user-guide-s05.png

196 KiB

docs/guides/img/user-guide-s06.png

15 KiB

docs/guides/img/user-guide-s07.png

110 KiB

docs/guides/img/user-guide-s08.png

79.5 KiB

docs/guides/img/user-guide-s09.png

77.7 KiB

docs/guides/img/user-guide-s10.png

33.9 KiB

docs/guides/img/user-guide-s11.png

9.02 KiB

docs/guides/img/user-guide-s12.png

34.1 KiB

docs/guides/img/user-guide-s13.png

7.78 KiB

docs/guides/img/user-guide-s14.png

9.04 KiB

docs/guides/img/user-guide-s15.png

11.8 KiB

docs/guides/img/user-guide-s16.png

17.7 KiB

docs/guides/img/user-guide-s17.png

23.2 KiB

docs/guides/img/user-guide-s18.png

24.9 KiB

......@@ -120,3 +120,191 @@ In order to subscribe to a given application user needs to open the details view
The third tab present on the top navigation bar named *Instances* contains information about all the application instances deployed within user’s domain. By default the displayed list of application instances only includes instances deployed by given user. It is possible to display all instances in given domain by selecting *All* in the *Show* selector. In addition it is possible to display all the instances that were already undeployed and which are hidden by default.
Application instances are described by custom Name assigned during deployment, name of the *Application*, selected *Version* of the application, user being the *Owner* of this instance (user who initiated the deployment), *Deployment time* and current *State*.
## 8. Application instance deployment
### 8.1 Application details view
On the application details page user can view a basic description of the application, example screenshots of the user interface, references to its website, code repository, website for registering issues and the versions of the application currently available on NMaaS.
![Application details](./img/user-guide-s05.png)
User can rate an application by selecting the appropriate number of stars, view the average rating and the rating breakdown. He can also add comments for this application.
Users can deploy instances of selected (subscribed) application clicking the *Deploy* button.
!!! info
Deploy option is only available for users with the *Domain administrator* role
### 8.2 Initiating application instance deployment
When deploying a new application instance user is requested to provide or select:
- custom instance name (unique within the domain, up to 10 lowercase characters)
- version of the application (from a drop down menu)
- chose to enable or not fully automatic application upgrades (triggered when new versions become available in the Portal)
- domain (in which given instance should be deployed)
The installation process comprises few steps including subscription validation, environment creation, verifying connectivity, application deployment, application first time configuration and activation.
![Application details](./img/user-guide-s06.png)
Once the installation process is completed user is provided with a way or multiple ways of accessing the deployed application instance depending on the application (in majority of cases a link for accessing the web-based UI).
!!! info
Providing a suitable instance name is important since it is later on used to create a FQDN unique for this application instance following pattern: <instance name>.<user domain name>.<NMaaS base domain> (e.g. vminstance.pllab.nmaas.eu)
!!! info
User is notified with an email once the new application instance becomes available
![Application deployment](./img/user-guide-s07.png)
### 8.3 Application instance initial configuration
During the installation process, once the application instance is initially deployed, user is asked to provide a initial configuration parameters for the application that is being installed. This data is entered through a configuration wizard presented in a window after clicking the *Configure* button which becomes visible on the application instance details page once the application transits to *Deployed* state.
![Application instance](./img/user-guide-s08.png)
Different type of data may be required depending on the application. Typically user is requested to provide credentials for a default account to be created at application startup or basic set of information about the equipment to be monitored by this application instance. Configuration parameters to be filled in are distributed over two or three tabs depending on the application.
Once all required fields are populated user can select the *Apply configuration* button to proceed with the application activation process.
### 8.4 Accessing application instance
Once the application instance reaches the *Active* state it can be accessed by the user.
Multiple access methods are supported by NMaaS and each of the applications supports one or more of them.
![Application access](./img/user-guide-s09.png)
Four types of access are possible:
- *public* - application user interface is accessible directly from the public Internet
- *external* - application user interface is accessible over HTTPS from within a dedicated client VPN
- *internal* - application is accessible over a different protocol than HTTP on a dedicated IP address (assigned by the system) and application specific port
- *local* - a Kubernetes service name that can be used to access this application instance from another application instance running within the same user domain (e.g. the local access information for a Prometheus instance can be used to configure data source in Grafana instance deployed within the same domain)
!!! info
If a given application supports only a single external access option then when selecting the *Access* button user will be redirected to the application interface directly
!!! info
In order to access the applications running within a particular domain user needs to connect to a dedicated VPN
### 8.5 Configuring application instance
Some of the applications support the option of updating its configuration during application instance runtime.
In such case, when instance is in *Active* state, the *Configure* button from the Actions menu on the application instance details page should be used to open a window presenting the configuration options.
![Application configuring](./img/user-guide-s10.png)
Typically a *git clone* link is provided that can be used by the user to locally clone the git repository created specifically for this application instance.
Then user can apply the desired changed to the pre-propulated configuration files added to the repository by default or add new additional files.
After the files are committed and pushed back to the repository the configuration of respective application is automatically reloaded within a couple of minutes.
!!! info
When cloning, user is authenticated using his private SSH key therefore is it necessary to upload the public SSH key on the user's *Profile* page prior to accessing the repository
!!! info
The user that initiates a given application instance deployment is automatically added to GitLab as a member of the newly created repository.
Other users, in order to have the same SSH-based access to the repository, have to be added as members to particular application instance using the *Members* button from the *Actions* menu. This operation can be performed by Domain administrator. Domain administrator can only select users that are added to his domain and have previously uploaded their SSH keys (see section 9.3).
### 8.6 Managing application instance upgrades
Once application instance is already running user is able to alter his choice regarding enabling automatic application upgrades using proper option available in the *Actions* menu. If during the initial deployment request user opted not to enable the upgrades he is provided with an option to *Enable automatic upgrades* and vice versa.
In case the automatic upgrades were not enabled user is still able to trigger application instance upgrades manually once a newer version of his deployed application is made available in the marketplace. In order to trigger the upgrade user should click on the *Upgrade* button from the *Actions* menu. Once clicked a window is displayed presenting detailed information about the possible upgrade to be performed including target application versions and corresponding target Helm chart version. Once confirmed, upgrade process begins in the background.
The fact that particular application instance can be upgraded is indicated on the Instances view by an up arrow icon displayed next to application instance.
!!! info
User is notified with an email once a manual upgrade of any of his running application instances becomes possible
!!! info
User is notified with an email once the upgraded application instance becomes active
### 8.7 Initiating application instance removal
In order to shutdown a particular application instance and free up resources that are no longer in use, user should click the *Undeploy* button from the *Actions* menu and confirm the action in window that pops up.
### 8.8 Managing failed application instance deployments
In unforeseen situations the deployment process may fail at some stage.
One of the following actions can be triggered by the user from the application instance view once deployment process ends up in Failure state:
- *Check state* - verifying if application instance is already running
- *Redeploy* - attempt to re-run the deployment process
- *Remove* - complete removal of the failed instance allowing a fresh deployment with the same custom instance name
!!! info
Administrators are notified with an email automatically once an application deployment process fails.
Users are encouraged to additionally inform administrators about the incident using the Contact Form.
## 9. User settings
### 9.1 User profile
User can view his account details and other personal settings by selecting the *Profile* option from the drop-down menu displayed after hovering over the username field on the top navigation bar.
![User profile](./img/user-guide-s11.png)
Profile view contains user account information such as: *Username, First name, Last name* and *Email*.
![User details](./img/user-guide-s12.png)
On the bottom of the page user can also see his roles granted in particular domains.
![User roles](./img/user-guide-s13.png)
By clicking on the flag icon located in the top right section of the view user can select his preferred language in which the content of the Portal will be displayed.
### 9.2 Settings user default Domain
One of the available options on the user's *Profile* view is specifying user's default domain.
![User preferences](./img/user-guide-s14.png)
This setting is particularly useful if a given user belongs to multiple domains and would like a specific domain to be selected by default after login.
### 9.3 Setting user SSH keys
For applications that support the Git-based configuration management model, meaning the possibility to update the application configuration during runtime by pushing updated configuration files to a dedicated Git repository, it is required that all users willing to use this option upload their public SSH keys using the form available on the *Profile* view.
![User SSH](./img/user-guide-s15.png)
![User SSH add](./img/user-guide-s16.png)
Upon key upload or update in the Portal, user information is synchronized with the user account created on the GitLab instance associated with given NMaaS installation.
### 9.4 Password change
On clicking the *Change password* button new window will be displayed where user can change his own password (see picture below).
![User change password](./img/user-guide-s17.png)
!!! info
This option is not available for users that log in using the Federated / SSO option
## Contact Form
An easy and recommended way for contacting the NMaaS Team is through the Contact Form.
Contact Form is available on the About page along with the information about the versions of the NMaaS software.
![Contact form](./img/user-guide-s18.png)
User can select one of five form types that best matches the subject of his message:
- *Contact* - generic request form
- *Access request* - for requests related with new account creation or role assignment
- *Issue report* - for reporting any encountered issues with the Portal or deployed application instances
- *New domain request* - for requests related with new domain creation
- *Enhancement or new application request* - for placing suggestions of enhancements, new features or integration of new applications
!!! info
Each type of form contains a different set of mandatory fields to be populated to best describe the subject of the message
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment