Difference between revisions of "Getting Started"

From Univention Wiki

Jump to: navigation, search
(Link to new documentation)
Line 1: Line 1:
Welcome! We are excited that you want to dive into Univention App Center and how to build your app.
#REDIRECT [[App Center Developer Guide]]
== 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 [https://www.univention.com/products/univention-app-center/for-solution-providers/ 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 [https://provider-portal.software-univention.de/univention-management-console/ 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:
[[File:App_portal_new_app.png|thumb|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.
# 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 [https://hub.docker.com/ docker hub] for example <code>univention/ucs-master-amd64:4.2-2</code>.
# 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:
* [[Docker_Apps/Image_Based]]
* [[Docker_Apps/Container_Scripts]]
* [[Docker_Apps/Persistent_Data]]
=== 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 <code>docker.software-univention.de/ucs-appbox-amd64:4.2-2</code>.
# 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.
=== Connector App ===
A Connector App &quot;connects&quot; 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 [https://www.univention.com/products/univention-app-center/app-catalog/google-apps Google Apps for Work Connector] and [https://www.univention.com/products/univention-app-center/app-catalog/office365 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:
# 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:
* [[Integration_with_UCS/Database]]
=== 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:
* [[Docker_Apps/Persistent_Data]]
== 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:
* [[Testing]]
== Questions? ==
You have questions during building and developing? Please visit the ''App Development'' section at:
* https://help.univention.com/c/apps/dev
== 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 ===
<li>Add a short description and a long description in the section ''Description'' on the ''General'' tab.
<dt>Short description</dt>
<dd><p>is shown on the app overpage in the tiles. It should be very short.</p></dd>
<dd><p>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 [https://www.univention.de/wp-content/uploads/2016/06/Recommendation-for-Optimal-Presentation-of-Apps.pdf tips &amp; tricks (PDF)] about what should be included here.</p></dd></dl>
<li>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.</li>
<li><p>Add translations for German at the ''Translations'' tab.</p>
<li>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.</li>
<li>Language specific screenshots and videos can be defined on this tab, as well.</li></ol>
=== 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 [https://en.wikipedia.org/wiki/Scalable_Vector_Graphics 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.
<li><p>At the tab ''Contact'' add links and email addresses about the vendor.</p>
<dt>E-mail address contact for customers</dt>
<dd><p>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.</p></dd>
<dt>Website with information regarding support options</dt>
<dd><p>is a link to a page on your website with detailed information about pricing, support and other offerings.</p></dd></dl>
<li><p>Section ''Vendor information'' at the ''Contact'' tab.</p>
<dd><p>If you are the vendor of the software, it is enough to fill out the vendor information.</p></dd>
<dd><p>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.</p></dd></dl>
<li><p>Add license information in section ''License''</p>
<dt>E-mail address for App install notifications</dt>
<dd><p>is the address where Univention should send notifications about registered users that installed the app.</p></dd>
<dt>Type of license</dt>
<dd><p>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.</p></dd>
<dt>License agreement</dt>
<dd><p>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.</p></dd></dl>
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:
* [[Category:App_Center_Developer_Guide]]
[[Category:App Center Developer Guide]]

Latest revision as of 14:54, 27 August 2018

Personal tools