fulgens v0.0.24

Fulgens

This software helps with building, deploying and running software locally. It is a shell script generator to orchestrate software components locally.

Fulgens also documents version compatibility for your software's dependencies like databases, Tomcat and Java.

It is not a tool to build software. It is not a tool to remotely deploy software. It is generally not a DevOps tool by any means.

The tool was made for software developers to document deployment dependencies like runtime environments and databases, as well as running it locally as easy as possible.

It standardizes "run this software locally", like maven standardized "build this software".

How to use it?

1.) Install via npm: npm -g install fulgens

2.) Create a Fulgensfile (there is an example down below)

3.) Execute fulgens in the same directory as a Fulgensfile and generate a bash script you can use to build, deploy and run your software locally. Start with fulgens | bash -s -- -h to read the help for your generated bash script.

Alternatively you can fulgens > run_local.sh to persist the generated bash script onto the filesystem.

If you've shfmt in your path fulgens will format the generated output via shfmt automatically.

A simple example / Tutorial

Create a Web project via: mvn archetype:generate -DgroupId=de.oglimmer -DartifactId=MyApp -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false. Step into the new project directory and create a minimal Fulgensfile with this content there:

module.exports = {

  config: {
    SchemaVersion: "1.0.0",
    Name: "example",
  },

  software: {
    "MyApp": {
      Source: "mvn",
      Artifact: "target/MyApp.war"
    },

   tomcat: {
      Source: "tomcat",
      Deploy: "MyApp"
    }
  }
}

Run fulgens>run_local.sh to create a bash script. Follow with chmod 755 run_local.sh to make it runnable and finally build, deploy and run via ./run_local.sh -f.

Now browse to http://localhost:8080/MyApp/

Now try ./run_local.sh -f -t tomcat:docker to run the Tomcat inside a Docker container. Or ./run_local.sh -f -b docker to build inside Docker, but run on your local machine.

Also checkout ./run_local.sh -h to see all available options.

Supported software

A Fulgensfile defines all software components needed to run a project. Supported software is

• maven (build)
• java (start)
• node (start)
• shell script (start)
• tomcat (host war files)
• mysql (database)
• couchdb (database)
• redis (database)

Futhermore Vagrant/VirtualBox is supported as well.

A Fulgensfile and its anatomy

A Fulgensfile may have the file extension ".js", it is recommended to name it "Fulgensfile.js".

A json-schema.org compliant json-schema file can be found here

The Fulgensfile is JavaScript file defining an (JSON) object and assigning it to module.exports.

It must contain two attributes

• config
• software

and it may contain a third attribute versions.

This is a minimal and basic Fulgensfile:

module.exports = {
  config: {
    SchemaVersion: "1.0.0",
    Name: ".....",
  },
  software: {
  }
}

The root object config

config defines overall configuration parameters.

The object Vagrant

Must be inside the root object config.

The object BuildDependencies

Must be inside the root object config.

The root object versions

This section is optional and can be used to define and document version compatiblity.

The root object software

All software components will be configured under software, by adding an attribute for each component like a mysql, doing a maven build or starting a tomcat.

There are no other attributes than software components. The attribute name is the software component name and can be freely choosen. The value is an object defining the software component. The only always required attribute per software component is "Source" which defines the type of software and thus plugin to be used.

Defining a maven software component

To build a Java project via maven, the maven plugin can be used to build locally or within a docker container. When doing a local build the -j JAVA_VERSION setting is respected.

Required and mvn specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeBuild, AfterBuild

Example software component for mvn:

software: {
	foo: {
		Source: "mvn",
		Artifact: "target/foo.war",	
	}
}

Defining a nodejs software component

To run a node.js application a local node binary can be used, it is also possible to start and run a Node application inside a docker container.

Required and node specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeBuild, AfterBuild, BeforeStart, AfterStart, ExposedPort

Example software component for node:

{
software: {
	foo: {
      Source: "node",
      Start: "src/server/start.js"
    }
}

Defining a java software component

A Java program can be started on the local machine or inside a docker container.

Required and java specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeStart, AfterStart, ExposedPort

Example software component for java:

software: {
  javaprogram: {
    Source: "java",
	 Start: "<<name of another software component>>"
  }
}

Defining a shell software component

A shell script can be started on the local machine or inside a docker container.

Required and shell specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeStart, AfterStart, ExposedPort

Example software component for shell:

software: {
  program: {
    Source: "shell",
	 Start: "<<name of another software component>>"
  }
}

Defining a tomcat to host a software component

To run a web application a fresh Tomcat can be downloaded, extracted and started, it is also possible to start and run a Tomcat instance inside a docker container. Also an existing local Tomcat installation can be reused.

Required and tomcat specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeStart, AfterStart, ExposedPort

Example software component for tomcat:

software: {
  tomcatWebServer: {
    Source: "tomcat",
    Deploy: "<<name of a different software compoenent>>",
    Lib: [ "<<name of a different software compoenent>>" ],
    SourceTypes: [ "download", "local" ]
  }
}

Defining a mysql database

A MySQL database can be started and used inside a docker container or an existing local installation can be reused.

Required and mysql specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeStart, AfterStart, ExposedPort

Example software component for mysql:

software: {
  "mysqlserver": {
    Source: "mysql",
    Mysql: {
      Schema: "my_new_schema",
      Create: [
        "src/mysql/initial_ddl.sql",
        "src/mysql/initial_data.sql"
     ],
     RootPassword: "root"
    }
}

Defining a couchdb database

A CouchDB database can be started and used inside a docker container or an existing local installation can be reused.

Required and couchdb specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeStart, AfterStart, ExposedPort

Example software component for couchdb:

software: {
  'couchdbserver': {
    Source: "couchdb",
    CouchDB: [{
      Schema: "toldyouso",
      Create: [ "src/couchdb/_design-User-view.json" ]
    }]
  }   
}

Defining a redis database

A Redis database can be started and used inside a docker container or an existing local installation can be reused.

Required and redis specific attributes:

Supported common attributes:

Git, Param, Dir, dockerImage, EnvVars, BeforeStart, AfterStart, ExposedPort

Example software component for redis:

software: {
  'redisserver': {
    Source: "redis"
  }   
}

Common attributes

Many attributes are supported by multiple types of software components.

This spreadsheet shows which plugins support which parameters: Plugin Parameter overview

Git

Fulgens can clone a git repository.

Param

A software component can be made optional. If done so a parameter must be given to the generated bash script to run the code for this software component.

Example:

software: {
  barDependency: {
    Source: "mvn",
    Git: "https://github.com/foo/bar.git",
    Dir: "$$TMP$$/bar-lib",
    Mvn: {
      Goal: "install"
    },
    Param: {
      Char: "o",
      VariableName: "BAR_LIB_ENABLED",
      Description: "Clone, build and install bar dependency"
    }
  }

Dir

A software component uses the same directory than the Fulgensfile by default. However the working directory can be changed by the attribute Dir.

BeforeStart and AfterStart

It is possible to execute shell code before or after a software component has started.

DockerImage & DockerMemory

Each software component type (plugin) has a docker image associated. This can be changed via this attribute, also it is possible to set the max memory parameter for the docker container.

EnvVars

This attributes allows the definition of environment variables. They will be passed to the application in an appropriate manner.

ExposedPort

When starter a docker container the system needs to know which port a component exposes.

BeforeBuild and AfterBuild

It is possible to execute shell code before or after a build (mvn/node) is done.

Config files

In Fulgens a software components can define config files. This mechanism allows it to override or add static configuration values, as well as to replace host names in configuration files at run-time.

Example:

config: {
    Name: "app.properties",
    Content: [{
      Source:"mysql",
      Line: "mysql.url=jdbc:mysql://$$VALUE$$:3306/schema"
    }, {
      Line: "bind=0.0.0.0"
    }, {
      Line: "user=foobar"
    }],
    AttachAsEnvVar: ["JAVA_OPTS", "-Dapp.filename=$$SELF_NAME$$"]        
    // or
    AttachIntoDocker: "/usr/local/etc/app/local.d"
}

Example files Fulgensfile.js

Many projects in oglimmer's github provide a Fulgensfile. Here is a list of real-world Fulgensfiles:

dsa-talent-calc-web

# Maven, dependency-build, Tomcat

A Java based web application which has a dependency to a different project (which doesn't live inan official maven repository).

See this Fulgensfile.js how to clone and build the dependency before building the Java web applicaton and starting it in a local Tomcat.

deckbuilder for swlcg and swccg

# Maven, Couchdb

Two very similar projects and their Fulgensfiles Fulgensfile.js, Fulgensfile.js building a Java project, starting an empty Couchdb before starting a Tomcat. These projects have a Dependencycheck added to their config section.

Code Your Restaruant (cyc)

# Maven, Tomcat, Java-Standalone-Backend

This Fulgensfile.js first builds a java project, then starts a Couchdb where it adds 3 views. The project consists of 2 parts, a backend server which is a plain java program and a war file hosted on a Tomcat. Both of them need config files.

Lunchy

# Maven, Mysql, Tomcat

A java web applicaton using a Mysql database. The Fulgensfile.js builds the java project, starts the Mysql, deploys the war file to the Tomcat and starts the Tomcat. To use utf-8 a config file is applied to the Mysql, after the database started the schema, tables and initial data is created via 'mvn -DcreateTables=true process-resources'.

Podcast human syncer

# Node, Redis

A very simple Node application, which uses a Redis database. The Fulgensfile.js just starts Redis and node.

Simple Card Game

# Maven, Tomcat

Most simple Fulgensfile.js. Just building a project and starting it on a Tomcat.

Told You So

# Maven, Couchdb, Tomcat, config-file, before/after Build

This Fulgensfile.js builds a project which needs a different pom.xml for java >= 9. It also startes a Couchdb and Tomcat.

Yet Another Tower-Defnese Game (yatdg)

# Maven, Tomcat

Most simple Fulgensfile.js. Just building a project and starting it on a Tomcat.

Linky

# Maven, Node, Couchdb, config-file, before/after Build, environment variables

This Fulgensfile.js starts with cloning the git repositoy of Lucene, building it and starting Lucene as a standalone java process. The a Couchdb is started and 2 schemas with initial views are created. Finally a node program is started. The Couchdb and Node have their own config files and Node is provided several environment variables.

Citybuilder

# Node, Couchdb, config-file

A Couchdb and a Node program is started in this Fulgensfile.js.

Grid Game One (ggo)

# Maven, Tomcat, Build-Dependency

Very simple Fulgensfile.js. It builds a project and starts it on a Tomcat.