Deploy an SmartSLA base on OpenPaaS with ease using Docker and docker-compose.

By default, the version used is the latest stable release of the OpenPaaS products, but you can also try the currently under-development version of components (activating the preview mode)

Disclaimer: this repository is intended for 2 use cases only: **running a demo** and **developping / debugging**.
You should never use it to run a production instance as it misses significant configurations to have your data secured and the produict sustainable.

• Setup your environement
• How to use
• Available modes
  • Demo mode
  • Preview mode
  • Dev mode
    • Frontend dev mode
    • Backend dev mode
• Manually setup
  • Create Software, Client and Contract
  • Create User
  • Create Issue
  • Types and Roles
  • Limesurvey
  • LinInfoSec
  • Roundcube Webmail
• Quick start
• Documentation
• User Feedback

Install the last stable version of docker && docker-compose following official documentation. Make sure that these are installed on your system before starting. NB: you can also install docker-compose using Python pip tool, see above :

# Using python package (you shoud use python virtualenv, cf virtualenvwrapper)
$ pip install docker-compose

Verify that you can execute docker commands as a non-root user, running: docker run hello-world If it doesn't work, see this documentation on how to run docker as a non-root user.

If root access is necessary for using docker, you are doing it wrong.

It is better to add your user account to the docker group

$ sudo usermod -a -G docker $USER

As there won't be any DNS resolving to your local environment, you must edit your /etc/hosts file to add new entries. That way, accessing http://frontend.smartsla.local with your browser will resolve to your local machine.

Add the following into your /etc/hosts file:

172.99.0.1      frontend.smartsla.local backend.smartsla.local limesurvey.smartsla.local lininfosec.smartsla.local webmail.smartsla.local

$ git clone ssh://[email protected]:7999/linagora/lgs/smartsla/smartsla-docker-dev.git
    # or
$ git clone https://github.com/smartsla/smartsla-docker-dev.git

Go into the project folder

$ cd smartsla-docker-dev

You can to gerate JWT keys following this commande :

$ ./assets/jwt-keys/init.jwt.sh gen-jwt-keys <subject>
# usage: gen-jwt-keys <subject>
#        subject format : /C=FR/ST=French/L=Paris/O=Linagora/CN=smartsla.org
# examples: gen-jwt-keys /C=FR/ST=French/L=Paris/O=Linagora/CN=smartsla.org

By default, the docker-compose commands will look for a file named docker-compose.yml in the current directory. In this repository, this will start the basic common services needed for an SmartSLA (LDAP, OpenPaaS...) but will not start the whole platform, so you will be missing most interfaces and applications.

This is meant to let you what part of the platform you want to run, since the whole platform can be quite heavy to run on a single machine.

To choose what to run or not, you will need to use a .env file, that specifies your COMPOSE_FILE env variable.

To do that easily, you can simply run:

cp .env.sample .env

In this file, you will find some setup examples commented. You can just uncomment the line you want to use, or create your own.

Notes:

• You should run docker-compose down --volumes --remove-orphans and docker-compose up -d when changing setup, to avoid orphan containers.
• You must have to have only 1 line uncommented in this file to avoid unwanted setup override

You are now all set! You can now use all the commands provided by the docker-compose tool. See: https://docs.docker.com/compose/reference/

To access the platform, check the URL set up in section Vhosts declaration. Check user accounts are in the file users.created.txt.

$ docker-compose pull

By default, running docker-compose up will create & start all containers in front. But when you exit the command, containers will be destroyed and data won't be kept (equivalent of running docker-compose down --volumes).

If you want to keep your containers and the data they contain temporarily, you can use start & stop:

$ docker-compose up -d   # Create containers and start them in background
$ docker-compose stop    # Stop all containers, but keep them
$ docker-compose start   # Restart existing containers that were stopped
$ docker-compose down -v # Stop & Remove all containers, local volumes and networks

Note: containers should be considered expendable. This mean that you should not rely on start & stop to save data you want to keep in the long run!
See the `Data persistence` section below.

$ docker-compose ps

Init containers must end up with exit 0. If no, launch again : $ docker-compose up

$ docker-compose logs    # Display logs
$ docker-compose logs -f # Watch logs
$ docker-compose logs -f esn # Watch logs for the ESN service

$ docker-compose down -v

Tip: If you want a quick command to tear down your environment and bring it completely fresh again, add the following to your ~/.bashrc or ~/.zshrc:

alias sarra="docker-compose pull && docker-compose down --volumes && docker-compose up -d"

We rely on compose to provide some custom setups, by overriding the base compose files using the COMPOSE_FILE env variable.

To activate a mode, your COMPOSE_FILE has to reference the following files, in this order:

1. docker-compose.yml, mandatory for all setups
2. docker-compose.[mode].yml, can't be used alone, they only override some part of the docker-compose.yml

The available modes are the following:

• Demo: use the released version of products
• Preview: use the most recent images meaning unreleased version of products, currently in development, instead of the latest stable released version
• Development mode: unplug one product of the platform from docker, to use your locally running development environment outside of docker

Your ESN instance is accessible at the URL http://backend.smartsla.local Your SmartSLA instance is accessible at the URL http://frontend.smartsla.local

This mode allows you to use the recently released version of SmartSLA products.

You need to export in your COMPOSE_FILE env the docker-compose.yml. Example of .env content with ESN:

COMPOSE_FILE=docker-compose.yml

That way, you get the recently released version of SmartSLA frontend and backend.

This mode allows you to use the most recent images of SmartSLA products, meaning the unreleased version currently under development.

You need to export in your COMPOSE_FILE env the docker-compose.preview.yml in addition to the basic docker-compose.yml. Example of .env content with ESN:

COMPOSE_FILE=docker-compose.yml:docker-compose.preview.yml

That way, you get the most recent version of SmartSLA frontend and backend.

To use dev mode, you need to export dev docker-compose, to add backend and frontend module, to create & start all containers, to configure ESN and SmartSLA to be able to run it in this order:

You need to export in your COMPOSE_FILE env the dev docker-compose for backend and frontend in addition to the basic docker-compose.esn.yml Example of .env content with ESN:

COMPOSE_FILE=docker-compose.yml:docker-compose.dev-backend.yml:docker-compose.dev-frontend.yml

That way, you get LDAP running in docker and a lightweight reverse-proxy instead of ESN, that forwards all trafic to your ESN nodejs server running locally.

2. • You need to do others steps for Backend development mode and for Frontend development mode

To use dev mode, you need to export dev docker-compose, to add smartsla-backend module, to create & start all containers, to configure ESN and SmartSLA to be able to run it in this order:

1. You need to export in your COMPOSE_FILE env the docker-compose.dev-backend.yml in addition to the basic docker-compose.esn.yml Example of .env content with ESN:

COMPOSE_FILE=docker-compose.yml:docker-compose.dev-backend.yml

That way, you get LDAP running in docker and a lightweight reverse-proxy instead of ESN, that forwards all trafic to your ESN nodejs server running locally.

2. You need also to add smartsla-backend module locally.

$ cd ../
$ git clone ssh://[email protected]:7999/linagora/lgs/smartsla/smartsla-backend.git
# or
$ git clone https://github.com/smartsla/smartsla--backend.git
$ cd smartsla-backend
$ npm i

3. You need to add esn locally and to create smartsla-backend symbolic link.

$ cd ../
$ git clone ssh://[email protected]:7999/linagora/lgs/openpaas/esn.git
# or
$ git clone https://github.com/linagora/openpaas-esn.git
$ cd esn
$ npm i

$ cd modules
ln -s ../../smartsla-backend/ smartsla-backend

4. Declare smartsla-backend module to esn modules list.

you will need to use a default.dev.json file, that specifies your modules list for development environment.To do that easily, you can simply run:

cd ../config
cp default.json default.dev.json

Add smartsla-backend to the modules list

  ...
  "modules": [
  ...,
  "smartsla-backend"
  ],
  ...

5. You need to run docker-compose up -d to create & start all containers.

$ docker-compose up -d 

6. Go into the ESN folder to add some configuration so that OpenPaaS will know how to to connect to its MongoDB database running in docker. This is possible with the OpenPaaS CLI.

Generate the config/db.json file first. This will be used by the nodejs application to connect to its MongoDB database running in docker. Add some configuration so that OpenPaaS will know how to access services :

$ cd ../
$ export ELASTICSEARCH_HOST=localhost
$ export REDIS_HOST=localhost
$ export MONGO_HOST=localhost
$ export AMQP_HOST=localhost
$ export [email protected]
$
$ node ./bin/cli.js db --host 172.17.0.1 --db esn_docker
$ node ./bin/cli configure
$ node ./bin/cli elasticsearch --host $ELASTICSEARCH_HOST --port $ELASTICSEARCH_PORT
$ node ./bin/cli domain create --email ${CURRENT_DOMAIN_ADMIN} --password secret --ignore-configuration
$ node ./bin/cli platformadmin init --email "${CURRENT_DOMAIN_ADMIN}"

172.17.0.1 is for linux. It's the IP where MongoDB launched by docker-compose above can be reached. You will have to set your docker-machine IP on OS X or Windows.

Only need to be done for the first time or after a docker-compose down -v

7. Run ESN & smartsla-backend locally.

Start the ESN server in development mode:

$ cd ../
$ grunt dev

Your local ESN server needs to:

• Listen on port 8080
• Connect to MongoDB running in docker, exposed on localhost:27017
• Connect to Redis running in docker, exposed on localhost:6379
• Connect to Rabbitmq running in docker, exposed on localhost:5672
• Connect to ElasticSearch running in docker, exposed on localhost:9200
• Have a the [email protected] platform admin account configured (for that, see node ./bin/cli.js db --host 172.17.0.1 section)

8. Run the esn-init job

Once ESN up & running, the esn-init job running in docker will call its API and configure other parameters like domain, LDAP connection...

$ docker-compose up -d esn-init

To use dev mode, you need to export dev docker-compose, to add frontend SmartSLA module, to create & start all containers, to configure ESN and SmartSLA to be able to run it in this order:

1. You need to export in your COMPOSE_FILE env the docker-compose.dev-frontend.yml in addition to the basic docker-compose.esn.yml Example of .env content with ESN:

COMPOSE_FILE=docker-compose.yml:docker-compose.dev-frontend.yml

That way, you get LDAP running in docker and a lightweight reverse-proxy instead of ESN, that forwards all trafic to your ESN nodejs server running locally.

2. You need to add smartsla-frontend module locally.

$ cd ../
$ git clone ssh://[email protected]:7999/linagora/lgs/smartsla/smartsla-git
    # or
$ git clone https://github.com/smartsla/smartsla-frontend.git
$ npm i

3. Start the frontend SmartSLA server in development mode:

$ npm run serve -- --port 8081

You can setup the SmartSLA manually with the following guide:

Browse to administration page and log in using - mail : [email protected] - password : secret

1. Select Roles → edit
   • In Users choose the admin
   • Hit Add

1. Select Software → create new software
   • Click on the '+' icon
   • Fill the fields Name
   • Hit Create
2. Select Clients → create new client
   • Click on the '+' icon
   • Fill the fields Name
   • Hit Create
3. Select Contracts → create new contracts
   • Click on the '+' icon
   • Fill the field Name
   • In Client choose the client created before
   • Fill fields Timezone, Business hours, Start date and End date
   • Hit Create
4. In Contract detail page,fill Supported software
   • Click on the '✎' icon and on the '+ ADD' button
   • Fill fields Software, Start date, Critical, Version and OS
   • Hit Create
5. Go back ← to the Contract detail page, fill each Contractual commitments
   • Click on the '✎' icon and on the '+ ADD' button
   • Fill fields Request type, Severity, Ossa identifier and Treatment time range of Business hours
   • Hit Create

Select Users → create new user - Click on the '+' icon - Choose the field Type - In the Search users field, found an LDAP user among this file users.created.txt. - Choose the field Role - If Beneficiary type → you need also to select Client and Contracts - Hit Create

1. Browse to home page
2. Select New issue in the menu
   • Fill the field Title
   • Select the Contract
   • Fill fields Type, Software, Severity and *Description
   • Hit Submit

there is two type of user :

• Beneficiary is a customer linked to a client and can create, see tickets
• Expert is part of the team handling the ticket

User roles are explain in the table :

Once limesurvey and postgresql are running, you can start using limesurvey home page.

You can follow the installation procedure for limesurvey 2.0

1. Click Next until you reach the Database configuration screen
2. Then enter the following in the field:
   • Database type PostgreSQL
   • Database location pgsql
   • Database user postgres
   • Database password limesurvey
   • Database name limesurvey #Or whatever you like
   • Table prefix lime_ #Or whatever you like
3. Activate /admin/remotecontrol API:
   • Go in http://limesurvey.smartsla.local/index.php/admin/globalsettings page
   • Select Interface tab
   • Enable Publish /admin/remotecontrol API (rpc_publish_api: 1)
4. Import survey:
   • Go in http://limesurvey.smartsla.local/index.php/admin/survey/sa/newsurvey/tab/import
   • Import survey : limesurvey_survey_491487
5. Init survey participants, this will create a table in database specifc to the survey created :
   • Click on survey participants button or go in this link: http://limesurvey.smartsla.local/index.php/admin/tokens/sa/index/surveyid/491487
   • Hit Initialise participant table
6. Active survey:
   • Click on active this suvey button or go in this link: active survey 491487
   • Select params fields
   • Hit Save & active survey
7. Set limesurvey config (needed to use limesurvey API)
   • Use Curl to set configuration:

     curl -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json'  http://backend.smartsla.local/api/configurations?scope=platform -u "[email protected]:secret"  -d '[
       {
         "name": "smartsla-backend",
         "configurations": [
           {
             "name": "limesurvey",
             "value": {
               "surveyId": 491487,
               "apiUrl": "http://limesurvey.smartsla.local/index.php/admin/remotecontrol/",
               "username": "admin",
               "password": "password",
               "limesurveyUrl": 'http://limesurvey.smartsla.local/'
             }
           }
         ]
       }
     ]'
     

SmartSLA can interface with LinInfoSec to provide quick notifications for vulnerabilities publications. To use it, add the docker-compose.dev-lininfosec.yml to the .env

• To enable it, use Curl to set configuration:

curl -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json'  http://backend.smartsla.local/api/configurations?scope=platform -u "[email protected]:secret"  -d '[
{
  "name": "smartsla-backend",
  "configurations": [
    {
      "name": "features",
      "value": {
        "isLinInfoSecEnabled": true
      }
    }
  ]
}
]'

Your Roundcube webmail can now be browse to webmail.smartsla.local.

To access the platform, check the URL set up in section Vhosts declaration. Check user accounts are in the file users.created.txt.

You can activate / deactivate features by editing openpaas.js file, here is the list of features:

• SSP_ENABLED set to true to allow users to edit their passwords

Once everything is running, you can start using SmartSLA home page.

Your ESN can now be browse to backend.smartsla.local.

You can connect with the default admin user :

Username: `[email protected]`
Password: `secret`

Don't forget to promote admin user as SmartSLA admin Browse to administration page and log as admin Select Roles → edit - In Users choose the admin - Hit Add

You can also log in as any other demo user, user accounts are in the file users.created.txt.

Official SmartSLA documentation is available here : https://smartsla.github.io.

If you have any problems or questions, please contact us through a GitHub issue.