Difference between revisions of "Getting Started"
From Univention Wiki
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.
- 1 Create the App in the App Provider Portal
- 2 Add the software
- 3 Persistent user data
- 4 Testing
- 5 Questions?
- 6 Add material for app presentation
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
- To start building your app, you should first get yourself an account in the app provider portal. Please request your personal account.
- You will receive an email with your username and instructions on how to set your password.
- Afterwards you can login to the App Provider Portal.
Create your app
- In the App Provider Portal select the Apps module in the Favorites or Software section.
- Click on Add a new App and provide the following settings:
- 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.
- In your app go to the tab Docker.
- Activate the checkbox Use docker container technology.
- Enter the name of your image to Docker image. Grab the name of your image from docker hub for example
- 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.
- Follow the steps 1-2 in image-based and set the Docker image to
- Upload your Debian packages at the tab Software in the section Debian packages.
- 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.
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.
If your solution stores data inside a database, please check the following at the Docker tab:
- Activate your preferred database management system in the section Database settings for docker container.
- Check the mapping of the database configuration options to docker environment variables in the section Environment database variables.
More information can be found at:
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:
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:
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
- 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.
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.
- 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.
Add translations for German at the Translations tab.
- 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.
- Language specific screenshots and videos can be defined on this tab, as well.
Logos, Screenshots and Videos
- 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).
- Add screenshots or other graphical material to present your product to the audience. On the tab Screenshots and videos you can upload graphic files.
- 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.
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.
Section Vendor information at the Contact tab.
If you are the vendor of the software, it is enough to fill out the vendor information.
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.
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: