businessConfig

Go application with an AdminLTE web frontend which is intended to be a tool for Product Managers.

Introduction

businessConfig is a program written in Go that turns simple text files containing data about an organization into pretty, intelligently-linked web pages. It is intended to be a tool for anyone who needs to quickly understand an organization, but especially Product Managers or consultants starting at a new company.

The idea is that the Product Manager or consultant sits with people from the organization with laptop in hand, listens to what they have to say, and records all relevant information quickly and easily in text files like the one shown above. The program then takes care of presenting the information in a pleasant and logical way.

This method has the advantage of being very fast and not relying on an internet connection when the information is being recorded (as opposed to a Wiki), and is OS-neutral and takes care of formatting for you (as opposed to a Word document). Additionally, you can commit the files into source control as if they were program files, with all the benefits that brings such as being able to link to tickets and track changes.

Each text file refers to an "entity" within the organization, e.g. a person or a process. The following entities and their connections have been implemented and can be shown in the web frontend:

The program automatically creates sensible links between the entities which are then reflected in the frontend, such as being able to see all members of a team in a list, even though team membership is defined as an attribute of a person. Also, only entities with associated text files are shown in the frontend so that, for example, if your organization doesn't have clients, you won't see the clients option in the website.

Features

Dependencies

The program is written in Go and uses several external packages in addition to the standard library:

  1. Install Go if necessary
  2. Go get the following packages:
    • github.com/go-fsnotify/fsnotify
    • github.com/gorilla/securecookie
    • github.com/gorilla/context
    • github.com/kennygrant/sanitize
    • golang.org/x/crypto/bcrypt

Local installation on Linux

  1. Go get the source code: github.com/macinntech/businessconfig
  2. Modify settings/settings.go according to your installation:
  3. cd to the program src directory
  4. Build the executable: go build
  5. Run the init command, this generates the admin user among other things. If running on a server, remember to change the username, email and password: ./businessConfig -source="Chicago Public Libraries" -init=true -username="AdminMe" -email="myemail@domain.com" -password="mypassword"
  6. Run the executable, giving source directory and port. If running on a server, remove the dev* flags: ./businessConfig -source="Chicago Public Libraries" -port="8081" -dev=true -devlogin=AdminMe
  7. Go to http://localhost:8081/ in your browser. In developer mode, the authentication is switched off, so you can just click "Sign In", and you should see the dashboard.

As long as you're using the program locally with the sample files, or with text files you generate yourself, that's all there is to it. Generate your files, run the program to point at your source, and off you go.

Thoughts on production use

I give no warranty for this program since it was written as a learning exercise and I have not yet used it in a production environment. But it is designed to deal with it, and here's how I would go about it.

Roles

There are 4 roles to consider once the program is in production:

  1. User. Creates and edits organization text files.
  2. Superuser. As User, but also administers users and resets passwords.
  3. Template/UI Developer. A UI developer or simply a power user who edits the templates. Minimal programming knowledge is needed.
  4. Go Developer. The developer who runs the executable, adds new entities, changes the way existing entity files are read, and generally ensures that everything works.

These roles are relevant for granting access to certain files/directories, as we will see below. Note that the User/Superuser roles are distinct for each data source served by the program, but the templates are SHARED by each data source.

Directory structure / visibility

Due to the different requirements of each role, I suggest the following directory structure on the server:

/home/ubuntu
    /go $GOPATH
        /src
            /github.com
                /macinntech
                    /businessConfig
            etc
    /businessConfig resource_dir in settings.go
        /webclient Shared only with UI devs
            /static
                /css
            /templates
                /inc
        /datasource1 Shared with source1 users
            /Clients
                item.txt
            etc
        /datasource1_priv
            users.txt Shared only with source1 superusers
        /datasource1_runtime Generated by source1 init command
            log
            pws
            views
            user_follows
        /datasource2 Shared with source2 users
        /datasource2_priv Shared only with source2 superusers
        /datasource2_runtime Generated by source2 init command
        etc

Updating the server

As noted above, changes to text files and templates are picked up by the program as soon as they reach the server. However, users will be editing files locally, so there needs to be a way to get them onto the server. I envisage this being handled either by Dropbox in an informal environment with 1 or 2 users, or proper source control in a more formal environment with many users who could potentially be editing the same files. In this way, the organization text files are treated the same way as code files, but with the Product Managers making commits. As a last resort, you could of course simply use FileZilla or the like to manually copy files to the server.

To be completed



comments powered by Disqus