Copyright 2019-2023 Demian Harvill
MProject is a microservice for describing and maintaining project management data. It is written in Go, and uses gRPC to define and implement it's application programming interface (API). The server requires a JSON Web Token (JWT) generated by the MService microsrvice for authorization.
Example client usage using the Go command line client (note that any thin client in any language supported by gRPC can be used instead):
projclient create_project --name myproject --desc 'example project' --sid 3 --sdate 2020-04-01 --edate 2020-06-01
Creates a project named myproject, starting on April 1, 2020 and ending June 1, 2020. The status is 3, which is has been defined by the create_status_type command (eg, not_started). Requires projadmin privilege.
projclient get_project_names
Gets the names of all projects in the account.
projclient get_project_by_name --name myproject
Gets information about a specific project, including the project_id.
projclient get_project_wrapper_by_name --name myproject
Gets detailed information (tasks and team member assignments) for a specific project.
projclient create_status_type --sid 3 --name not_started --desc 'project or task has not been started'
Create a value in the status type enumeration used by the project and tasks. This is at the account level and applies to all projects. Requires projadmin privilege.
projclient get_status_types
Get a list of all status types.
projclient create_task --pid 1 --name kickoff --desc 'project kickoff meeting' --sid 4 --sdate 2020-04-01 --edate 2020-04-01 --priority 1 --position 1
Create a new task (kickoff) within myproject, as the first task. Requires projadmin or projrw privilege.
projclient create_project_role_type --rid 1 --name manager --desc 'project manager'
Creates a value in the project role type enumeration. This is at the account level and applies to all projects. Requires projadmin privilege.
projclient get_project_role_types
Get a list of all project role types.
projclient create_team_member --pid 1 --name 'Big Guy' --email [email protected] --rid 1
Creates a team member to work on the project. Requires projadmin or projrw privilege.
projclient get_team_member_by_project --pid 1
Get a list of team members assigned to the project
projclient add_team_member_to_task --tid 1 --mid 3
Assign a team member to a task. The task id (--tid) can be discovered with get_tasks_by_project. The member id (--mid) can be discovered with get_team_member_by_project. Requires projadmin or projrw privilege.
projclient add_task_hours --tid 1 --mid 3 --hours 3.5
Add hours to the total that a team member has worked on a task. Requires projadmin or projrw privilege.
Other commands for operations (eg. get, update, delete) can be discovered with
projclient
with no parameters.
The generated JWT uses RSA asymmetric encryption for the public and private keys. These should have been generated when installing the MService microservice; in particular, the mproject server needs access to the jwt_public.pem public key.
In a production environment, the connection between the client and the MService server should be encrypted. This is accomplished with the configuration setting:
tls: true
If using either a public certificate for the server (ie, from LetsEncrypt) or a self-signed certificate, the server need to know the public certificate as well as the private key.
The server configuration is:
cert_file: <location of public or self-signed CA certificate
key_file: <location of private key>
The client configuration needs to know the location of the CA cert_file if using self-signed certificates.
There are MySql scripts in the sql/ directory that create the mproject database (mproject.sql) as well as all the required tables (tb_*.sql). These need to be run on the MySql server to create the database and associated tables.
The persistent data is managed by a MySQL / MariaDB database associated with this microservice.
No data is shared across MService accounts.
The root object is a project, which is associated with a single MService account.
A project contains a tree where each node is a task, so tasks can have subtasks recursively. Every task is assigned a status based on status type, which is also aggregated to the project level.
Each individual working on the project is a team member. A team member has a role within the project as described by project role type. Team members are assigned to tasks by task to member, which also records the hours worked on a task by that team member.
To build the server:
cd cmd/projserver
go build
The projserver executable can then be run. It expects a YAML configuration file in the same directory named conf.yaml . The location of the configuration file can be changed with an environment variable,PROJ_CONF . Configuration can also be specified on the command line or through environment variables (with PROF_ prefix)
projserver -h
Usage:
invserver [flags]
Flags:
--cert_file string Path to certificate file.
--conf string Path to inventory config file. (default "conf.yaml")
--db_pwd string Database user password.
--db_transport string Database transport string.
--db_user string Database user name.
-h, --help help for invserver
--jwt_pub_file string Path to JWT public certificate.
--key_file string Path to certificate key file.
--log_file string Path to log file.
--port int Port for RPC connections (default 50052)
--tls Use tls for connection.
A commented sample configuration file is at cmd/projserver/conf.sample . The locations of the various certificates and keys need to be provided, as well as the database user and password and the MySql connection string.
A command line client written in Go is available:
cd cmd/projclient
go install
It also expects a YAML configuration file in the user's home directory, ~/.mproject.config. A commented sample for this file is at cmd/projclient/conf.sample
Running the executable file with no parameters will write usage information to stdout. In particular, all subcommands expect the user to have logged in with Mservice acctclient to establish the JWT. The JWT is also used to determine which account is being used for the command.
Note that the use of the Go projclient is merely a convenience, and not a requirement. Since we are using gRPC, the thin client can be written in any supported language. It can be part of a web or mobile application for example.
The mproject microservice relies on the projsvc claim, and the following claim values:
projadmin: administrative access
projrw: read-write access to mproject objects
projro: read-only access to mproject objects
Note that within an account in Mservice, a role must be created to map these claims to a logged-in user.