1 General Principles

StageOS’ website gives you the possibility to create projects on which you can, if needed, work as a group of several users, including during exploitation and maintainance phases.

We automatically and dynamically create the pipeline that will let you manage your continuous integration and deployment, from start to finish.

An artificial intelligence watches your sources while commiting, and deduces the compenents to be integrated in your pipeline, then triggers it up to the step you previously chose, until the automated launch of your application through secured and efficient (Docker/Kubernetes ) containers exposed through AWS.

The project is hosted under StageOS’ Gitlab, and we guide you through its usage all along this tutorial, in StageOS’ context.

Tips : to enlarge an image, just click on it !

2 Sign Up on StageOS

As a first step, you are required to sign up on stageos.io. It is a mandatory step and will not take long! You will then receive a confirmation email, in which you will find a link to validate your account on our website. Once this step done, you can start creating your project in your personnal space.

(#fig:sign_in) identification screen

Anytime, you can reset your password or retrieve it through the link forgot your password? available on the sign in screen.

3 Manage my projects

After signing in, you have access to your projects. Please note that this step will get faster on your next use of StageOS, that will automatically put you back in your context through different mechanisms, among which SSL (we will see below how and where to declare your RSA key).

3.1 Create a project

Initially, the project interface is empty, and you are invited to click on the bleu + sign in order to create a new project.

(#fig:my_project_empty) creating projects

Prior to the creation of a project, you can create a token, copy it and store it for a future usage. We will se below that this will let you easily clone other repositories, to insert them properly in your project.

(#fig:my_token) generating a token

You can now access the interface to create your projects. Be very careful to how you will chose to name your project, and the comments you will apply to it, as it will be the base of your group work, and help your partners identify clearly the subject of the project.

Please note that you can invite other people anytime to the projects, with different roles. For now, you are still alone and your role is maintainer of the project, which grants you a full access to it.

(#fig:create_project) creating a project - details

After a little while, your project is created. We have configured Gitlab with your initial credentials, and we also created the users you have invited to the project. Those users inherit the rights attached to their given roles. As an example, a developer will not be able to manage your project.

We created a project through Gitlab, which explains why it is represented by this product’s icon.

(#fig:my_projects) my projects

You can then access the overview of your project by clicking on its icon.

You are now on the main interface of StageOS: on a regular usage context, it is possible this is the one and only interface you will interact with daily. We will later see that it is possible for you to identify the status of every flow linked to technical works generated by StageOS, to make it go through all the build and deployment stages of your project (from build to deployment, through Q&A).

DevOps pipelines are automatically set through the parsing of your repository during a commit. The interface will let you check the status and the state of their execution in just a few seconds.

For the moment, let’s concentrate on the top part of the interface.

(#fig:project_interface) Project management interface

Please note that you can decide at any moment to switch your project to “public”, opening it to the StageOS community. You can also switch it any time to private with the public/privte tool.

Your project is labeled with a mini internal identifier, a number (here 565), don’t be surprised!

You don’t have a status on your pipelines yet, for you haven’t produced or cloned anything in your Gitlab repository.

You can now click on the URL to the Gitlab repository automatically generated for you, that looks like the following:

  https://xxxx.stageos.io/first-project-565/first-project.git

Warning : StageOS manages security for you, it will therefore as you to sign on the repository through its own mechanism (Stage OS button).

(#fig:sign_with_stageos) automatic credentials to your repository

From now on, access your project directly on Gitlab.

Here we are, the project is a little empty, and no stars of forks are there yet, but everything is possible!

(#fig:first_project) my projects

To be absolutely operationnal and secure, you must accept as soon as possible to create a couple of RSA keys (public and private) to setup the SSL mecanism and manage rights in your work groups, one or several material, and Gitlab. Please note you can generated several keys and destroy them as well.

Under the command line of your Linux/Mac/Windows machine (or via Putty or Kitty on Windows, using the same parameters), you can type, by using your own email adress:

ssh-keygen -o -t rsa -b 4096 -C "my_email_adress@site.extension"

You now have to name your file (this will generate 2 files), Warning! Make sure to identify the path to both files, and store it in a safe and private place!

Enter file in which to save the key (paths ...) :

We recommend you to chose a paraphrase, a string of characters that protects the access to your keys.

You will just have to open the file public key and cut/paste the key inside where required by Gitlab.

$where it is required to paste your public key$

(#fig:ssh_coller) where it is required to paste your public key

Here you go, after clicking on _Add key__, you are done with basic configuration of your project, and you are now operationnal and good to start!

3.2 Destroying a project

Be careful, for this action is permanent.

It is of common knowledge that most developers work on a local environment and regularly proceed to push their environment on the common workspace, here the project your just created: it then creates a kind of local backup of your information. However, destroying the project will make you loose all logs about updates from the different actors and available information in the project wiki (among others).

In any case, we always recommend to regularly clone your project in order to have updated backups available at all time (through Git mecanisms, which are documented on our Gitlab interface).

Of course, StageOS was thought to automatically save what’s required to preserve your application safe and functionnal at all time.

To destroy a project, click on the red ( x ). You now have one last chance to go back, using the Cancel button.

(#fig:delete_project) project destruction

4 Hello world !

4.1 How to prepare an application for your Hello world

In order to build and deploy an application with StageOS….only one thing is required : an application to build and to deploy!

We assume here you have at your disposal such an application to deploy in a language and a context of technical dependencies that we already support (please refer to the updated list at the end of this tutorial).

This application must be as follows:

it does something, for example it exposes on the web an html page where “Hello World” is written or it exposes a Restful API returning “Hello World”. It can of course be a lot more complex.
Optionnally :
- in order to build it, you used one or more package and dependancy managers, and there is somewhere one or several files (.json, .yaml …) describing those links : we will take it into account.
- your files are structured as you chose, and this structure is composed of source files but not only: there are also configuration files and unit tests definitions: we will parse this structure.
- you use tools to manage your unit tests and/or other middlewares: we automatically process those tools if we already support them (please refer to the updated list at the end of this tutorial).
- some dependancies are not externally declared, but are seen in the code (import of a package…) : we will process your code to build the application with a logical versioning of those dependancies.
- you make it mandatory for us to build your application with a given dependancy, or a given version of interpretor… : we provide you with a configuration file (optionnal) to let you indicate this mandatory part and we will follow this specific requirement. We will also use this specific requirement to define qll other dependancies according to this one.

We have built a repository for your project hosted in our StageOS infrastructure. Our work is based on the commits you will make on this repository to trigger our processes of parsing, of artifical intelligence, of construction, test and deployment for your app. It is possible to feed it in several ways:

Direct intervention in the Gitlab, available for you: manual upload of your sources and commits in the master branch to launch our automatic processes.
Use of your local Git and clone and push of your loca Git repository toward our infrastructure using the available token (you can generate it at any time, as explained above).
Use of a distant repository, such as Git or Gitlab (two options are then possible: use your local repository or clone and push directly using mecanisms we will make available for you through the token.

4.1.1 case N°1 : create your code in your project’s Gitlab

Let’s assume you want to create the following Python/Flask application :

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello World from Flask!"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

The object of this application is to expose your “Hello world”. In our Gitlab, you can create a file (by cpoy/pasting the code in an Edit mode)

(#fig:add_new_file) Creating a source file

You then have to make a commit on the master branch, which will launch our AI:

Figure 4.1: Commit on the master branch

You will find the status of your pipeline in the main interface:

(#fig:build_config_running) Commit on the master branch

If needed, you can retrieve the list of all your activities in the Gitlab.

Figure 4.2: Commit on the master branch

However, we noticed that most of the users like to use the pipeline view of our main interface better, which doesn’t display any useless information.

4.1.2 case N°2 : local git –> StageOS

In this case, which is the most commun, you only have to:

generate a token (you can refer to the above, it only requires one click on our interface), and store it
identify the Gitlab url we created for your project, and login through StageOS
to initiate the process, clone this repository to your local git, using your CLI for example (Gitbash…):
- place yourself in the targetted folder (cd ..)
- create an environment variable for the token:
```
export STAGEOS_TOKEN = _paste_here_your_token_
```
- clone the StageOS repository :
```
git clone https://MyToken:$STAGEOS_TOKEN@url_of_your_stageOS_gitlab your_new_local_repository
```
- don’t panic if it says it’s empty, the first time….it’s true!
Now you only have to copy your project structure with your source files in your local repository :
- copy what’s useful in the folder of your repository
- make sure your .gitignore excluded the useless files
- add everything under Git configuration management:
```
git add -A
```
- update the repository anytime it’s necessary:
```
git commit -am "a message to remember what's up"
```
- once you think you have a testable or deployable app, push it to StageOS :
```
git push
```

Our artificial intelligence launches itself and takes the lead.

Obviously, in the case where you work directly on our Gitlab on “manual” mode, a simple commit of your project on the master branch will trigger our AI.

On your project interface on StageOS, you now see the status and history of all your actions and the corresponding processes’ states (pipeline).

Your project is immediately taken into account, and according to the load of our systems at this moment, it can be pending for for a little time :

Figure 4.3: Pending

Then the project is processing :

Figure 4.4: Processing

You have access anytime to the state of the pipelines leading to the tests or the deployment of your application live by clicking on Detail :

(#fig:detail_running) Processing

We easily distinguish a failing process from a woll-going process :

(#fig:failed_vs_running) One of the processes failed

5 FAQ : Your most Frequently Asked Questions

5.1 What skills do I need to use StageOS ?

StageOS was thought and built for developers who know how to create an application that works on their machine, who want to go further, and who either don’t have the skills or the time to do so, or don’t have the necessary tools available to proceed in good conditions of performance and reliability.

Those developers must confront themselves to the problem of construction, test and deployment of their application in an operationnal context, and deploy skills that we usually refer to as “Devops”.

StageOS doesn’t require to have DevOps skills, but it requires a basic knowledge of Git and continuous integration and deployment that might help using the tool at its best. However, as proven all along the above tutorial, you can see how little skills are required to make a basic use of StageOS.

5.2 Which technical prerequisites are mandatory to use StageOs ?

To use StageOS, the following are required :

a machine for development, with an internet connexion through which the website is accessible.
an application to test and/or deploy.
optionnal : a git repository on the machine or on a deported website.

5.3 How is the artifical intelligence of StageOS useful ?

The variety of use cases and the constant evolution of “assets” in terms of software dependancies, “pipeline”, configuration options, skills in creating micro-services or containers orchestration make mandatory the management and the combination of various rules. There are infinite possibilities for all those rules and events to combine, and it requires the use of an artifical intelligence in order to be efficient, flexible and performing. This is the main point of the non-determinist AI we created.

5.4 Available languages and products

You can work in the following contexts :

Python
- Testing tools
- Frameworks : Flask, Django
- Machine learning packages : Tensorflow
NodeJS
- Testing tools
- Package managers

5.5 Kubernetes

Is it mandatory to have a Kubernets at my disposal ?

No, but you can subscribe to one in order to deploy automatically.

Stageos-gitlab-howto