= !MapGuide RFC 160 - Enhanced command-line support =

This page contains a change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||9 Jun 2017||
||Last Modified||14 Jun 2017||
||Author||Jackie Ng||
||RFC Status||Implemented||
||Implementation Status||complete||
||Proposed Milestone||4.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Jackie,Gordon,Crispin||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This RFC proposes to add support in the mgserver executable with extra command-line capabilities to facilitiate automated/scripted setup and configuration.

== Motivation ==

MapGuide is very easy to install in a headless/automated manner, making the process of putting MapGuide inside a docker container or other automated provisioning/deployment processes quite simple.

However, what is a bit difficult at the moment is to automate the process of configuring/provisioning MapGuide's resource repository and being able to set/change the passwords of built-in users

Such functionality exists in the MapGuide API, but that requires the MapGuide Server to be actually running first.

In an automated deployment/provisioning scenario, this presents an awkward chicken-and-egg problem where you can't do such actions without some coordination to have your setup code (that uses the MapGuide API) have to wait for the server tier to become online first before running the setup code.

== Proposed Solution ==

Enhance the command-line capabilities of mgserver to support:

 * Loading a package file
 * Setting the Administrator password

=== Package Loading ===

Usage will be as follows:

{{{mgserver loadpackage <path to package file>}}}

In this mode, the MapGuide Server will initalize the required services (same way as unit testing), load the given package through MgResourceService.ApplyResourcePackage and exit

=== Setting Password for built-in users ===

Usage will be as follows:

{{{mgserver setpwd <mapguide username> <password>}}}

In this mode, the MapGuide Server will set the account password of the specified built-in user to the value provided from the command line.

This command solves this long-standing ticket (#581)

=== Command classes ===

To make adding support for new commands in the future an easier task, this RFC also refactors the ServerCore code to use command classes. A new abstract {{{MgServerInteractiveCommand}}} is introduced to model a particular {{{mgserver}}} command.

{{{
// The base class of all interactive commands
class MgServerInteractiveCommand
{
protected:
    MgServerInteractiveCommand();

public:
    virtual ~MgServerInteractiveCommand();

    virtual INT32 Execute() = 0;
};
}}}

From this, this RFC adds the following subclasses:

 * {{{MgTestCommand}}}: For {{{mgserver test}}}
 * {{{MgTestFdoCommand}}}: For {{{mgserver testfdo}}}
 * {{{MgLoadPackageCommand}}}: For {{{mgserver loadpackage}}}
 * {{{MgSetPwdCommand}}}: For {{{mgserver setpwd}}}

In {{{MgServer::ParseArgs()}}}, we now set the appropriate command pointer and in {{{MgServer::svc()}}} we now check for a set command pointer, which if set we instruct it to {{{Execute()}}} and capture its return code. Otherwise we proceed with normal service (or interactive) startup

== Implications ==

The {{{setpwd}}} command does a blind {{{UpdateUser}}} call on {{{MgServerSiteService}}} (this API will throw if the user id does not exist). However, this will blank out the user name (not related to user id) and description properties of the user whose password is changed through this command. To preserve this information would require an {{{EnumerateUsers}}} call, manual parsing of the XML response to find the details of the matching user and calling {{{UpdateUser}}} with the preserved information and the new password. 

Due to this information not being essential (it is merely descriptors of the user accounts), it was decided for the simplicity of implementation that losing such information through this command was an acceptable trade-off.

This implementation resides in the ​[http://trac.osgeo.org/mapguide/browser/sandbox/jng/cmdline cmdline] sandbox. Upon adoption of this RFC, it will be merged into trunk.

== Test Plan ==

 * Verify we can still run {{{mgserver}}} interactively and as a service
 * Verify new commands perform as expected
 * Verify we can still run unit tests through the refactored test command
 * Create a MapGuide docker image that auto-loads the Sheboygan dataset via {{{mgserver loadpackage}}} and changes the Administrator password via {{{mgserver setpwd}}}. Verify that when running the built docker container, that we can load the AJAX viewer with the Sheboygan Web Layout straight away (the sample data should've already been loaded) and login to the Site Administrator with the changed password.

== Funding / Resources ==

Community