Difference between revisions of "Getting Started"

From Univention Wiki

Jump to: navigation, search
(Angelegt.)
(No difference)

Revision as of 13:10, 27 April 2018

Welcome! We are excited that you want to dive into Univention App Center and how to build your app.

Create the App in the App Provider Portal

The app provider portal is the app developer's self service place for all the settings around the app.

Account in App Provider Portal

  1. To start building your app, you should first get yourself an account in the app provider portal. Please request your personal account.
  2. You will receive an email with your username and instructions on how to set your password.
  3. Afterwards you can login to the App Provider Portal.

Create your app

  1. In the App Provider Portal select the Apps module in the Favorites or Software section.
  2. Click on Add a new App and provide the following settings:
Create your app
App ID
is like a primary key. You should choose it carefully, because it cannot be changed once the app is released to the public. It should use small capitals, dashes and numbers. Please do not include version strings in here.
App Name
is the name of your app. It is used to display the app on the overview pages. This attribute can be changed any time.
App Version
is the version of your app. The App Center distinguishes versions and uses them to handle app updates.
UCS Version
is the UCS version your app should start be available on. See UCS_Versions for further explanation.
File under
is refers to the organization that the app belongs to. Please select your organization here or otherwise the will not show in the listing for you.

That's all you need for the beginning.

Add the software

At the heart of an app is usually some pieace of software that is installed on UCS.

Image based Docker App

The easiest way to build an app for Univention App Center is to use your docker image provided to the world via docker hub.

  1. In your app go to the tab Docker.
  2. Activate the checkbox Use docker container technology.
  3. Enter the name of your image to Docker image. Grab the name of your image from docker hub for example univention/ucs-master-amd64:4.2-2.
  4. Set the docker entry-point in the section Advanced docker settings at Entrypoint for the Docker App.

Warning: Please add the version tag explicitely. The App Center distinguishes different app versions and handles updates accordingly.

Note: The App Center does currently not support multi container setups with docker compose. The app container needs to include all services needed for the software, except the database. The App Center takes core of providing a database management system directly on the docker host that can be used by the docker container. Supported are MySQL and PostgreSQL. See add-database.

For more configuration and customization options:

Package based Docker App

If your software is not available as docker image, but it is provided as Debian packages, please use the UCS based docker image and let the App Center install your packages via apt-get into this container.

  1. Follow the steps 1-2 in image-based and set the Docker image to docker.software-univention.de/ucs-appbox-amd64:4.2-2.
  2. Upload your Debian packages at the tab Software in the section Debian packages.
  3. Set the package(s) that should be installed by apt-get in section Installation packages at Required debian package for App installation. If you have one package that installs all the other packages because of package dependencies, please enter it's name here.

Connector App

A Connector App "connects" the UCS environment with the hosted solution of your software. The connection is a good idea for solutions that need user identities and can connect to external user account databases. UCS will then function as identity provider for the solution and takes care of the authentication. Examples for such apps are Google Apps for Work Connector and Microsoft Office 365 Connector.

A connector app basically takes care of the following functionality:

User Provisioning
to create, update or delete customer's user accounts in the solution using any kind of remote API.
User Authentication
to authenticate the users with their credentials against the identity provider.

The most flexible way is to use the image-based approach for the connector.

Persistent user data

Docker apps need to take care of user data handling in case a container is exchanged with a new one. There basically two places where user data is stored: A database and in files in directories in the container.

Add database

If your solution stores data inside a database, please check the following at the Docker tab:

  1. Activate your preferred database management system in the section Database settings for docker container.
  2. Check the mapping of the database configuration options to docker environment variables in the section Environment database variables.

More information can be found at:

Add volumes

If your solutions stores user data in files within directory in your container, those directories should be mounted as volumes from the host. The data is actually stored on the host and not in the container and thus simplifies the exchange of containers.

Please check the section Mounted volumes at the Docker tab and add an entry for each directory mapping. More information can be found at:

Testing

Building/Developing an app is an iterative cycle of change and testing. It involves the App Provider Portal, the Test App Center and a UCS system that you use for testing purpose.

After you created the app and added software, you can start your first testing. For testing, please follow the instructions to download UCS and activate the Test App Center:

Questions?

You have questions during building and developing? Please visit the App Development section at:

Add material for app presentation

Having the software ready and working within the app is one half of the tasks. The other half is to take care of decent presentation of the app. Text should be first entered in English and translated to other languages, e.g. German, in a second step.

Texts and translations

  1. Add a short description and a long description in the section Description on the General tab.
    Short description

    is shown on the app overpage in the tiles. It should be very short.

    Description

    is the primary text informing the prospect about your solution, what problem it solves, what target group it addresses and what benefits it offers for operation on UCS. We have curated some tips & tricks (PDF) about what should be included here.

  2. Add optional README information at the README files tab. The texts are shown at different steps in the life cycle process. For example, information about the first steps can be shown to the user after the app is installed.
  3. Add translations for German at the Translations tab.

    1. Every text that has been entered in the other sections can be translated there. In principle there are two text fields. The original text is in the top field and the translation has to be entered in the field below.
    2. Language specific screenshots and videos can be defined on this tab, as well.

Logos, Screenshots and Videos

  1. Add the logos for the overview and detail page in section Logos on the General tab. The default logo should have a square ratio. The required format for logos is Scalable Vector Graphics (SVG).
  2. Add screenshots or other graphical material to present your product to the audience. On the tab Screenshots and videos you can upload graphic files.
  3. Add videos on the same tab. YouTube is supported only.

Contact and License

App users should know who is the app provider and what are the conditions under which the app is offered.

  1. At the tab Contact add links and email addresses about the vendor.

    E-mail address contact for customers

    is shown to the user and the channel that the app provider offers to the user for contact. Most app providers offer their default contact address here.

    Website with information regarding support options

    is a link to a page on your website with detailed information about pricing, support and other offerings.

  2. Section Vendor information at the Contact tab.

    Vendor

    If you are the vendor of the software, it is enough to fill out the vendor information.

    Maintainer

    If you are not the vendor of the software, but the entity who takes care of the app and its life cycle, please fill out both, the vendor and the maintainer information.

  3. Add license information in section License

    E-mail address for App install notifications

    is the address where Univention should send notifications about registered users that installed the app.

    Type of license

    is one of five categories about how the software can be used. Free commercial use, some functions are liable to costs, free trial or liable to costs. Choose one that suites best to your software.

    License agreement

    is a text that is shown to the user before the software can be installed. The installation is only continued, if the user accepts the text. The license is optional.


So far the part to get you started with the app. For detailed information on different topics around app development for Univention App Center have a look at:

Personal tools