Skip to content

Deploying LiberouterGUI

Jump to bottom
Jakub Man edited this page Jun 14, 2018 · 24 revisions

Table of Contents

  1. Introduction
  2. Installing modules
  3. Installing internal dependencies
    1. Frontend dependencies
    2. Backend dependencies
  4. Deploying system itself
    1. Development version
    2. Production version

Introduction

Make sure you meet the dependency requirements before deploying anything.

There are two ways how to run Liberouter GUI:

  1. Development
  • Frontend is run in development mode which slows the whole page down (longer loading times).
  • Frontend is able to report errors with line numbers and more precise errors.
  • Frontend reloads every time you change a file in frontend/ folder.
  • Backend runs in debug mode (Flask's debug mode) with extensive reporting of errors and events.
  • Requests from frontend are proxied via Angular CLI to standalone-running backend (using Flask server).
  1. Production
  • Frontend code is compiled into static minified .js files, index.html, CSS and assets.
  • You must specify base-href if the frontend is run outside root folder of webserver.
  • Backend should be run via WSGI and proxied according to frontend configuration.

This guide details both approaches, but the first step is bootstrapping modules you want to have in Liberouter GUI. This process is the same for both approaches.

1. Installing and Bootstrapping Modules

Once you have decided on what mixture of your own modules and "official" modules for Liberouter GUI you want to run, you can clone them into the modules/ folder. Modules developed by CESNET organization are guaranteed to work that way, for the third party modules please double-check the presence of config.json with module's root.

NOTE: By 'guaranteed to work' we mean that module does not require any additional steps before it can be bootstrapped. You still have to perform feature configuration. For example, SecurityCloud module requires paths to various binaries and auxiliary files to be configured as these are not installation independent.

With the modules in place, you can run the python bootstrap.py located in the root of lgui project. If it finishes without any message, huzzah! If it reports any errors or warnings, try to resolve them and run it again.

Bootstrapping symlinks backend/frontend code of each module to proper folders within Liberouter GUI, merges all dependencies into package.json, .angular-cli.json and requirements.txt, adds frontend assets and generates a file that tells Angular to include the frontend sources into main app.

2. Installing Internal Dependencies

Once you successfully bootstrap modules, you have to install dependencies. This step has to be performed each time you update your modules both by adding a new one or updating existing one.

**NOTE: Each time you change structure of edit module's configuration you must bootstrap Liberouter GUI again and check for correct changes.

2.1 Frontend Dependencies

Go to frontend/. Run this command:

npm install

2.2 Backend Dependencies

Go to backend/. At this point, you can set up virtual environment for python3 and the packages you're going to install. If you don't want to, just skip the following step:

virtualenv venv --system-site-packages -p python3
source venv/bin/activate

Now simply tell pip to install the dependencies from a file:

pip3 install -r requirements.txt

If you're using virtualenv run deactivate to exit it now.

3. Deploying System Itself

3.1 Development Version

Follow this guide if you're creating a new module, otherwise use the production deployment. For the next steps, screen utility may come in handy as you will be running two (three) separate processes and want to see their outputs.

First off, start whatever database server you fancy and Liberouter GUI is supporting. As you might now need output from this one, you can run it as a service.

3.1.1 Backend

Second, we'll be running the backend part. Before you can run anything, co to backend/ and rename config-sample.ini to config.ini. Then activate virtual environment (if you opted to using it). After that, return to root of lgui project and run:

python3 backend

3.1.2 Frontend

Go to frontend/ and run following command:

In order to use ng command you need to install angular-cli globally. This can be done via this command: npm install @angular/cli -g.

ng serve --proxy-config proxy.json

If you are using older versions of LiberouterGUI, before migrating to Angular 6, you should start development server with:ng serve --proxy proxy.json --preserve-symlinks

If you need advanced features of Angular CLI and the serve command you can consult the official documentation.

If both backend and frontend started properly, open your browser on localhost:4200. Try to log in, Liberouter GUI will detect first time startup and redirect you to the setup page, where you'll create the admin account and then you can login to Liberouter GUI with the newly created credentials.

3.2 Production Version

Apart from running the database, production version behaves quite differently. Instead of having frontend dynamically recompiled each time you'll edit a source code, production version compiles all sources into *.html and *.js files that will be server by Apache (or your favourite web server). Python backend will be executed via persistent wsgi.

3.2.1 Backend

You need to install mod_wsgi for your web server to be able to make rest of this guide to work. In case you are using Python3.4 and CentOS7, which does not have correct version available for the apache, do the following:

yum install httpd-devel gcc
pip3 install mod_wsgi
mod_wsgi-express module-config >/etc/httpd/conf.modules.d/00-wsgi.conf
systemctl restart httpd

With the proper wsgi module installed, you need to configure /etc/httpd/conf/httpd.conf. In README in backend/ you can find configuration for secure connections, following configuration is simplified for local use:

ErrorLog '/tmp/log.txt'
LogLevel info

<VirtualHost *:80>
    DocumentRoot "/var/www/html/"
    WSGIDaemonProcess libapi threads=5
    WSGIScriptAlias "/libapi" "/path/to/backend/wsgi.py"
    WSGIPassAuthorization on

    <directory "/path/to/backend">
        WSGIProcessGroup libapi
        WSGIApplicationGroup %{GLOBAL}
        WSGIScriptReloading On

        Options All
        AllowOverride All
        Require all granted
    </directory>
</VirtualHost>

Don't forget to set up proper paths within that configuration. Also make sure that this path is open for reading for the apache user. In case of any errors, check /tmp/log.txt file for more info the matter. SELinux is known to cause a lot of headaches.

3.2.2 Frontend

For the sake of the guide, we'll be serving frontend from /var/www/html/lgui. In frontend/, instead of ng serve execute this command:

ng build --prod --base-href="/lgui/" --aot=false --build-optimizer=false

For older versions of Liberouter GUI, before migrating to Angular 6, use ng build --prod --bh="/lgui/" --aot=false --preserve-symlinks

For more info about ng build command consult official documentation.

After a successful compilation, there should be now directory frontend/dist. Copy all of its contents to /var/www/html/lgui. Please note that --base-href (--bh in older versions) parameter determines path to root of the gui from root of the web server. Apache has its root at /var/www/html and thus path to root og ui is /lgui/. Do not omit the final slash!

Make sure that within lgui/assets there is a config.json. Restart httpd and at this point your web browser should be able to load and display login screen of Liberouter GUI at http://localhost/lgui/.

Clone this wiki locally