Development Environment

Using Docker

Traditionally, development environments have been setup directly on the user's machine using a combination of RPMs, bash scripts, and symlinks. Today we instead recommend using Docker to more quickly setup these environments.

Setup

1. To get started, first clone the OESS git repository to your Docker host.
2. Navigate to the root directory of the OESS software project.
3. Copy .env.example to .env and populate the relevant fields:

   cp .env.example .env
   vi .env
   

4. Build the base Docker image:

   make container
   

5. Start the development environment:

   make dev
   

6. At this point you should be dropped into a live container. To load the base database and start OESS run:

   /entrypoint.sh
   

7. After starting OESS view system logs using:

   tail -f /var/log/oess.log
   

Start Another Terminal Session to the Development Container

Sometimes it's useful to open another terminal into your OESS Container. To do this first identify and copy the ID of your OESS Container using:

docker container ls

Next, use the Container ID from the previous step and then run:

docker exec -it <container-id> /bin/bash

Working with your Database

Schema Changes

Database Schema

Any time the database is updated be sure to edit perl-lib/OESS/share/nddi.sql. This is the base database schema and is used for every installation.

Database Upgrade Script

TODO

Create an upgrade script in perl-lib/OESS/share/upgrade if one does not already exist.

Test Databases

If you've made changes to the database schema you'll want to make sure the test databases are updated to reflect the change. To do this first ensure the oess and oess_test databases are not in mysql, then load the database you want to update into mysql. We do this to ensure that all database fields are updated properly.

Before continuing: There are two unit test databases, t/conf/oess_known_state.sql and t/conf/mpls/discovery.sql; These use the oess_test database. There is one integration test database, t/conf/integration.sql; This uses the oess database. Be sure to update all three databases whenever making schema changes.

1. Remove the existing database to create a clean slate.

mysql> drop database oess_test;
mysql> exit;
$ mysql -u root -p < t/conf/oess_known_state.sql

2. Next make your changes to the database schema.

$ mysql -u root -p oess_test
mysql> alter table node modify column maintenance_id int(11) NOT NULL;
mysql> quit;

3. After you've made your changes use mysqldump to save the modified database.

$ mysqldump -u root -p --databases oess_test > t/conf/oess_known_state.sql

Backups

If you'll be needing the data from your existing database again, use mysqldump to backup your database. This can be useful when switching between sets of test devices.

$ mysqldump -u root -p --databases oess > database-backup.sql

To reload your data:

$ mysql -u root -p
mysql> drop database oess;
mysql> quit
$ mysql -u root -p < database-backup.sql

Soft-Reset

A soft-reset removes all provisioned Connections and interface ownerships are removed. Run the following sql commands after selecting the oess database to perform a soft-reset.

delete from acl_history;
delete from vrf_history;
delete from history;

delete from link_path_membership;
delete from path_instantiation_vlan_ids;
delete from path_instantiation;
delete from path;

delete from circuit_edge_interface_membership;
delete from circuit_instantiation;
delete from circuit;

delete from vrf_ep_peer;
delete from vrf_ep;
delete from vrf;

delete from cloud_connection_vrf_ep;

update interface set workgroup_id=NULL;

delete from user_entity_membership;

Hard-Reset

To remove all connections, approved network devices, and links first run the mysql commands from soft-reset then finish up with the below commands. No users or workgroups will be removed.

delete from link_instantiation;
delete from link;

delete from interface_acl;
delete from interface_instantiation;
delete from interface;

delete from node_instantiation;
delete from node;