Get started tutorial

In this tutorial we guide you step by step to :

  1. create you first atom skeleton
  2. push your code to the Plug'In repo
  3. automate and publish your atom documentation
  4. automatically deploy your artifacts of the Playground

Tip

For a better experience, you may want to use a linux machine that have an access to gitlab.tech.orange

Note

In the following, when a text is written between less-than < and greater-than > signs, it means that it is a custom variable that you need to update with your own information.

Atom Generator

The AtomGenerator is a cookiecutter template for Plug'In atoms.

You can find very useful information on how to use this generator here.

Please note that all atoms hosted on Gitlab need to be (started) using this template.

This template may evolve. In this case a migration script will be provided.

If you have a specific requirement for a particular project please feel free to raise an issue or directly propose your template to the Plug'In community.

For more information about Plug'In, please visit our plazza page.

Recommendations

When you create a documentation markdown file, make sure to use the following rules:

  • - or _ should be used instead of a space in the file name
  • A file name should be in lower case (layout is taken in charge by AtomDocs)
  • The length of a file name should be less than 30 characters
  • Limit line width to 80 columns (in vim you can use: set cc=80)
  • The use of the rst file format is permitted but not recommended
  • File name should be as descriptive as possible of its content

Communication

We created a mattermost channel for each working group. Feel free to use any other tool that fits your needs.

Do not forget to share your experience with the community and keep the open software spirit.

Here is the list of the channels:

  1. Connectivity as a Service channel

  2. EASI and Beyond-EPC channel

  3. Infrastructure Health and Lifecycle channel

  4. OpenAirInterface channel

  5. Sandbox channel

Repository Organization

The official git repository of the Plug'In project is the Orange Forge Gitlab. Gitlab offers a nice web interface to manage projects.

For better organization of the repository, multiple roles are defined:

  1. Owner: is the admin of all groups and projects in this repository

  2. Master: a master of a group can manage the group, its subgroups and its projects

  3. Developer: pushes code to projects in his/her group

Groups were based on the Working Groups of Plug'In (DevDays of June 2017).

For instance, 5 Plug'In working groups are identified:

  • Connectivity as a Service
  • EASI and Beyond-EPC
  • Infrastructure Health and Lifecycle
  • OpenAirInterface and
  • Sandbox.

Each WG has at least two masters.

Create a Gitlab project

To create a Gitlab project in the group you manage: go to the corresponding group in https://gitlab.tech.orange/plugin/ ; click on the New Project button; provide a good description of your project and you're done.

Create an Atom

Go to atomgen repository in Gitlab to learn how to install and start using cookiecutter.

The AtomGenerator template will do many things for you by asking some questions, for example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
atom_name [myLucyAtom]:
atom_summary [my Atom_name does THIS]:
atom_description [my Atom_name does THIS]:
Select atom_category:
1 - Authentication & authorization
2 - Application Programming Interface
3 - 5G
4 - Integration
5 - Monitoring
6 - Multimedia
7 - Networking
8 - Organization
9 - Internet of Things
10 - Tools
Choose from 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 (1, 2, 3, 4, 5, 6, 7, 8, 9, 10) [1]:
...

One important thing is that cookiecutter generates a local git repo for you. All you need to do is to add some configurations and push the local repository to the remote one using the following commands:

1
2
3
4
5
git config --global user.name "<username>"
git config --global user.email "mail@orange.com"
git remote set-url origin https://<ldap-id>@gitlab.tech.orange/plugin/<wg-name>/<project-name>.git
git push -u origin --all
git push -u origin --tags

Now your code should be available online on the Gitlab repository.

Create Atom documentation in AtomDocs

To make your atom's documentation available in AtomDocs you need first to create some documentation.

Thanks to AtomGenerator, a skeleton for your atom documentation is created for you.

We are going to use the default README.md file and docs/ folder.

Using Gitlab-CI

To automate the upload of your atom documentation to AtomDocs, You will use Gitlab-CI Pipeline.

CI/CD Variables For Atomdocs Job

In gitlab, you can use CI/CD Variables that will be passed to the gitlab runner as environment variables. For more information about Gitlab Variables, please visit this link.

  1. Go to your Gitlab project settings/CI/CD and expand the Variables panel
  2. Create the following variables, presented in key/value format :
    1
2
3
4
5
    LUCY_ATOMDOCS_CI_SERVER/10.192.34.223:3000
TOKEN_NAME/7a860be650ed14dcaa05fe89341a8ae0
LUCY_ATOMDOCS_USER_CREDS/lucy:atomdocs
LUCY_ATOMDOCS_FILE_SERVER/90.84.179.70
JENKINS_JOB/atomdocs-build-ext-docs

CI File

If you created your atom using Atomgen, you should have a .gitlab-ci.yml file.

Make sure that your .gitlab-ci.yml is the latest version.

if you don't have this file, apply the following steps:

  1. Create a .gitlab-ci.yml file in the root of your atom's code
  2. Insert the content of this file into your .gitlab-ci.yml file.

Once you push your atom now, your documentation will be updated in AtomDocs.

Note that .gitlab-ci.yml contains also a job for publishing the atom to Atomstore, so remove it if not interested.

Versionning

You may have several versions of your Atom, but docs that are committed to AtomDocs are always the latest branch you run the Gitlab-CI pipeline on.

Automate Publishing Your Atom in Atomstore

Automation is done by sending two requests to Atomstore using the Gitlab-ci pipeline:

  1. Atom registration/update request.
  2. Atom release publish/update request.

The administrative staff will review the requests and approve it if it's ok.

The first step to automate your atom publishing is to make sure you have:

  1. Atomstore account.
  2. the latest version of our .gitlab-ci.yml template, for more info.

CI/CD Variables For Atomstore Job

  1. Go to your Gitlab project settings/CI/CD and expand the Variables panel.
  2. Create the following variables, presented in key/value format :
    1
2
    ATOMSTORE_SERVER/90.84.172.223
API_TOKEN/<your-atomstore-api-key>

    To Get Your Atomstore API-Key, login to Atomstore and goto (Account -> API Token).

Appinfo Directory

If you create your atom using Atomgen:
1. You should have appinfo directory in the root of your atom's code.
2. the appinfo directory contains two files (info.json, version.json).
3. info.json and version.json should have basic info about your atom(You can add more info by checking the APIs guide).

Those files treated as the request body of the two Automation Atomstore APIs:
info.json: treated as request body of the Atom registration/update API.
version.json: treated as request body of the Atom release publish/update API.

If you don't have this directory, apply the following steps:

  1. Create appinfo directory in the root of your atom's code.
  2. Create two files info.json, version.json.
  3. See the Atom registration/update API Body Request and fill info.json with appropriate values.
  4. See the Atom release publish/update API Body Request and fill version.json with appropriate values.

When you push your atom, your a Gitlab-ci Job will run and send two requests to the Atomstore.

Once your requests approved by the administrative staff, you will see your atom created on the homepage. If your atom or atom release already exists in the Atomstore, your requests will be treated as update requests.

IMPORTANT NOTES:
  1. You should publish a release with a version at least (1.0.0) to see your atom in the homepage.
  2. You should maintain info.json and version.json to keep your registered atom in the Atomstore updated.

Continuous integration enhancements

If you already know the Plug'in Playground, you may want to experiment with your builds as soon as your CI/CD Job finishes. In the following you will learn how to do this using the plugin_deploy atom.

The TL;DR copy and paste version

This project is at the same time the deployment script and an example of automatic deployment.

  • Deploy images

Copy the following section in your .gitlab-ci.yml if you want to deploy a session with a docker image you just built. Change the --docker-image switch to whatever image you built or want to deploy. The image can be from Artifactory, Gitlab registry, or Internet (using the artifactory dockerproxy)

Do not forget to add the stage "deploy" to your stages of the job.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
deploy_image:
  variables:
    VERSION: "0.1"
    SESSION_DURATION: "1h"
  stage: deploy
  image:
    name: registry.forge.orange-labs.fr/$CI_PROJECT_PATH:$VERSION
  tags:
    - innovation
    - docker
    - shared
  script:
    - deploy.py --session-duration $SESSION_DURATION --deploy image --docker-image registry.forge.orange-labs.fr/$CI_PROJECT_PATH:$VERSION --log-level debug --html-output-file $PWD/rapport.html
  artifacts:
    paths:
      - rapport.html
    expire_in: 1 day
  • Deploy compose files

Copy the following section in your .gitlab-ci.yml. The resulting session will have your compose images built and ready to use. In this example, the compose folder in the project contains all that docker-compose.yml needs. Try to have a similar structure and adapt your --compose-dir and --compose-file variables as you see fit.

Do not forget to add the stage "compose" to your CI stages.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
deploy_compose:
  variables:
    VERSION: "0.1"
    SESSION_DURATION: "2h"
  stage: compose
  image:
    name: registry.forge.orange-labs.fr/$CI_PROJECT_PATH:$VERSION
  tags:
    - innovation
    - docker
    - shared
  script:
    - deploy.py --session-duration $SESSION_DURATION --deploy compose --compose-dir $CI_PROJECT_DIR/compose --compose-file docker-compose.yml --log-level debug --html-output-file $PWD/rapport.html
  artifacts:
    paths:
      - rapport.html
    expire_in: 1 day

Go further

Look at you! You started here and now you want to go beyond! Good for you and the Plug'In community!

Any suggestion of enhancements, topics, better documentation, software or other should come from the community and returns to it. We have detailed ways of how to contribute in our portal, please reach out!