# Install SlapOS Master (COMP-ROOT)

This tutorial will guide you through the steps of installing and configuring a SlapOS Master to manage a network of computers. It will use the single line installer (for other ways, see experimental ways to install SlapOS Master). Once completed you will have a COMP-ROOT node similar to that of slapos.vifib.com, Nexedi's cloud hosting provider, which can then be used as starting point for creating a network of nodes to provide software instances.

Before starting this tutorial, make sure you have read the SlapOS architecture and SlapOS system requirements in order to make yourself familiar with the terminology and overall concepts.

For completing this tutorial, it is required to have a fresh server (Debian 8 or 9) with command line access and wget installed. The tutorial will use an arbitrary server from a cloud provider such as OVH or Online.net).

Note, that Debian 8 and 9 are tested daily and can be installed from binary cache, meaning installation will take between 15-30 mins depending on the machine. Other Linux distributions are also supported by the single line installer, but source code may have to be compiled from scratch meaning installation will take around 6-7 hours.

# Table of Content

- Installing SlapOS Master
- Configure SlapOS Master
- Create First User

# Installing SlapOS Master

The currently recommended way of installing a SlapOS Master is using the single line installer.

# Verify Debian Version

    debian@slapostest:~$ lsb_release -a
    No LSB modules are available.
    Distributor ID: Debian
    Description:    Debian GNU/Linux 8.9 (jessie)
    Release:        8.9
    Codename:       jessie

Start by ssh-ing into your server and verifying the Debian version using:

    lsb_release -a

# Call Single Line Installer

    sudo su
    # wget https://deploy.erp5.net/slapos-master-standalone
    # bash slapos-master-standalone

Change to root user and call the single line installer.

This will download, build and install the required packages (ansible, slapos-node, slapos-proxy), configure the computer as a SlapOS standalone node, and deploy SlapOS Master (ERP5) and a Frontend (Apache) service inside. Note, that, as mentioned, in case the required files are not available from binary cache, compilation may take several hours.

# Check Compilation Status

    TASK [standalone-shared : Check ERP5 state] ************************************
    fatal: [127.0.0.1]: FAILED! => {
      "changed": true,
      "cmd": "/usr/local/bin/erp5-show -s",
      "delta": "0:00:00.059622",
      "end": "2018-03-02 10:08:44.316161",
      "failed": true,
      "rc": 2,
      "start": "2018-03-02 10:08:44.256539",
      "stderr": "",
      "stdout": "Your software is still building, be patient it can take a while",
      "stdout_lines": ["Your software is still building, be patient it can take a while"],
      "warnings": []
    }

Once the loader finishes its first run it can fail with the above message.

This is expected while the software is compiling!. You can rerun the script above or check the status of the installation directly by calling:

    erp5-show -s

# Verify Successful Installation

    # erp5-show -s
    Build successful, connect to:
    https://[IPv4.adress.xxx]
    with
    username: zope  password: [xxx-password-xxx]

Once installation has successfully completed, the status message will be similar to the one displayed above. It means the SlapOS Master is ready to be configured.

Run the bash script one final time to check there were no errors,

    root@localhost:/home/debian# bash slapos-master-standalone
    ...
    PLAY RECAP *********************************************************************
    127.0.0.1                  : ok=56   changed=15   unreachable=0   failed=0

Note down the url provided along with the username and password.

# Configure SlapOS Master

The installed SlapOS Master is actually an ERP5 instance with specific business templates providing the functionality to manage users, software releases, hosting subscriptions, usage consumption etc. It is referred to as the ERP5 Cloud Engine. For more details please refer to the slapos architecture design document and general introduction to SlapOS.

The following steps include accessing the ERP5 cloud engine interface "underlying" SlapOS to launch the ERP5 configurator plus activating email settings and portal alarms so that the SlapOS Dashboard can work as expected.

# Access SlapOS Master ERP5 Interface

Start by going to the URL (`https://[IPv4]`) provided and append "/erp5/" to the URL which will take you to directly to the ERP5 interface. Login with the username and password you have received when the installation of the Master finished (run `erp5-show -s` in the terminal).

# Configure Mailhost

In order for regular users to use the SlapOS Dashboard, registration is necessary and requires providing an email address (for verification and account activation). This in turn mandates configuration of mailhost and site information in the ERP5 cloud engine so that emails are correctly forwarded.

Open `https://[IPv4]/erp5/MailHost/manage_main` to access the mail host configuration in the Zope interface (ERP5 is built on top of Zope). Add a SMTP mailhost and login/password for the alias under which an email should be forwarded/sent. Make sure the Port is also correctly set to your email provider's correct SMTP port. Click Save changes when done to continue.

# Update Email Sender

Open `https://[IPv4]/erp5/manage_propertiesForm` and add the fields email_from_name and email_from_address to send emails from a valid sender and reduce the chance of emails being labelled as spam. Click Save changes to continue.

# Activate Portal Alarms

Open `https://[IPv4]/erp5/portal_alarms/manageAlarmNode` select an Alarm Node (admin-0), click Change and then click Subscribe.

# Launch Configurator

Back in the erp5 interface (`https://[IPv4]/erp5/`) you can see that the initial ERP5 instance is almost "empty" - it only contains basic features and modules. ERP5 uses so-called business templates (bt5s) to add specific features (such as CRM, project management, etc.). Templates can be added one-by-one or in bundles for which there are various configurators. A configurator for adding the SlapOS Master business templates and upgrade this ERP5 to an ERP5 Cloud Engine has already been provided during installation. To run it, click on My Favorites and select Configure your site which will take you to the available configurators.

# Launch Configurator

Only one configurator should be available. Select it by clicking Configure and confirm the installation on the subsequent screen (not pictured) by clicking "install" again.

# Configuration Progress

There is a progress indicator (which does not show actual progress!) visible for the duration of the configuration. Configuring SlapOS Master may take between 15-60 minutes depending on the server being used.

# Configuration Progress

The page will update once the configuration has finished. Click on Start Using your new ERP5 System. If the link takes you to the login form, there is no need to login again. Just go the homescreen of the ERP5 instance at `[IPv4]/erp5/`.

# Manager Certificate Authority Tools

As a last step the SSL Certificate Authority tools have to be linked. Head back to the Zope interface to:

    https://[IPV4]/erp5/portal_certificate_authority/manage_editCertificateAuthorityToolForm

and set `/etc/slapos-ssl/` as absolute path. (Note: When setting up SlapOS Master on webrunner, you should set the path to `/srv/slapgrid/[your partition]/srv/ssl/`)

Click save, then don't forget to head back to your terminal and restart the SlapOS Master node using:

    slapos node restart all

It is required to flush internal caches. Wait a few seconds so ERP5 can restart before heading back to the ERP5 interface.

# SlapOS Master ERP5 Homescreen

Back on the homescreen you can see the updated number of modules available after configuration. It is beyond the scope of the SlapOS documentation to introduce the ERP5 interface. However you will be able to find many elements in the list of modules which will be used through the SlapOS Dashboard (such as Computers or Hosting Subscriptions for example). The SlapOS Dashboard is also part of ERP5 and can be found in the Web Sites module (called hostingjs).

Note, that the zope username/password you are currently using is only meant for developing ERP5 itself. It is not an actual user account which would have an entry in the person_module. To continue, you have to create a first actual user of your SlapOS network by registering through the SlapOS Dashboard.

# Create First User

To use services provides on a SlapOS network, users are required to register. The SlapOS Dashboard provides a registration form (described here) as well as several social media logins (should not be used) to register and create an account in the person_module of a SlapOS Master.

Note, that some Masters such as Vifib will charge for usage of their network and only activate accounts manually after settlement of an initial invoice. By default activation is done automatically once the user verifies his email address.

# SlapOS Master - Login

Go to your SlapOS Master Dashboard (`[IPv4]/erp5/web_site_module/hostingjs/` - make sure to not forget the trailing slash). Note, that to register a new user through the SlapOS Dashboard, you need to be logged out of the underlying ERP5 interface. To start the login, click Create New Account.

# SlapOS Master - Register New User

Fill out all the required fields and click Register New User. You will receive a confirmation email to activate your account. Click on the activation link in this message to confirm your email address.

# SlapOS User - Activation Pending

Note, make sure to check your spam folder for the activation email message as it is sometimes ending up there. In the email you received, click the activation link which will send you back to the login screen. You will receive a second email (!) telling you that your account has been activated and is accessible.

Note, that the redirect url is still malformed at the time of writing! Please login at `[IPv4]/erp5/web_site_module/hostingjs/` to not get a rendering error. In case you have inadvertently tried to login, please logout again and login at the correct url!

# SlapOS User - Dashboard

Once your account is activated you can access the SlapOS Dashboard with the credentials you selected. Also note that this is an empty user account without any servers or services.

# Validate SlapOS User Contract

The SlapOS user you just created isn't allowed to instantiate any service until its contract is validated (for a commercial use of SlapOS, you wouldn't want anyone to be able to instantiate something before checking he will be able to pay).

In order to validate the contract, you must first logout from your user account and log back to SlapOS ERP5 master at https://[IPv4]/erp5/login_form with "zope" user (= super user). Then go to https://[IPv4]/erp5/cloud_contract_module and type "%" in the Title search bar and type Enter. You should see one contract for the user you just registered.

Click on the contract, then Action - Validate as seen on the screenshot. Your user is now authorized to instantiate services.

The setup of SlapOS Master is complete. You can now start to request services available on your network.

# Thank You

- Nexedi SA
- 147 Rue du Ballon
- 59110 La Madeleine
- France

- nexedi.com/contact