Setting up a server to publish Archimate models

I have just finished a project where I had to set up a publishing service for Archimate models in my enterprise. I’d like to share some thoughts about it. The solution is designed to be as simple and stupid as possible but the “the devil is in the details” (not sure this phrases means anything in english…)

What it should do

  • The models should either be hosted in our internal gitlab instance or directly on the publishing server
  • The models should be exported daily (and automatically of course) to html sites with standard Archi export features
    • the publishing server is the smallest VM I could ask for (1vCpu/2Gb Memory/40 Gb Drive, and it is still an overkill)
    • I use Linux Server with just Apache Web server and Archi.
    • Archi runs on this server in headless mode
    • Note there is no need to update the website as soon as a commit is pushed to a model, refreshing each website daily is more than enough.
  • Some models contains “hidden” views and anybody should not be able to access them
    • Archi offers a view property ( _hide_from_export ) that hides the view in the menu of the exported websites, but I had to go further and effectively delete the html files and images from the website. This way, someone reading the html source code cannot get the view url. This is all done in bash script.
  • “Hidden” views should be accessible to some users
    • Each models is published twice : one website without hidden views and one website with the hidden views.
    • The private website is protected by Shibboleth. Through SAMLv2, user must be authenticated to our LDAP enterprise server and be granted a dedicated role, prior to get access to this site.

All in all, it does not seem a lot to do but it took around 40 days to setup everything including v2 (see below), write documentation, follow various processes. Yes we are a 100% agile company… and a 200% slow enterprise too.

Some more features…

There are a lot of “hidden” things and features in these 40 days :

  • Tools to help support in administering and monitoring the solutions I have to say that the server is not operated by our standard IT operator (long story shorts : It would have taken 4-5 additional months, I could not afford it), so I added tools to purge logs, send email on disk 80% full, and so on.
  • Minor features like adding
    • the date/time the website was generated,
    • a light version of the menu so that it loads faster on Edge browser.
    • a welcome portal page,
  • Security, I may be a little paranoid here but as an architect I feel my own applications should be commendable on these aspects :
    • Tools that check nobody is tampering with the published models and send alerts
    • a dedicated firewall to further protect the server
  • Migrate the legacy website (generated by Mega Hopex) without destroying hyperlinks that were done long ago to the legacy diagrams.
  • (a lot of) documentation as I am leaving my job, I had to write everything down for a potential successor.
  • For this reason, I have anticipated the development of the V2 version which provides
    • Archistory : a jArchi script which generates a visual diff between snapshots of a model, so that everyone can easily see what have been changed in views between two dates.
    • Although my bash script which delete hidden views works like a charm, I have gone one step further and have written a jArchi Script that before export, deletes the view and every concept in the model that only appears in hidden views.
    • A REST API which can be used by other applications (or end-users) to query the published models
      • the API is coded in Python, with Flask and Flassger (for the swagger generation)
      • the data are read from OEF files generated daily by Archi.
      • the API offers few endpoints to get Single Point of Trust for any given business object, provides permalink to view with human readable parameters (not internal id but name of the application and the type of view you want to see)

What I have learned

  • Using jArchi on the server side adds a lot of value. In my use cases :
    • it is a lot easier to purge the models from the views I want to hide
    • It allows to automate Archistory process (get the latest model, compare it to previous one, generate the diff pages …)
    • Disclosure : I have not deployed it on my production server because Archimatetool is still not referenced in our SAP environnement so that we can not support Archi development.
  • There is a lot of data in your models, plan time to implement mechanisms so that everyone may not access or alter sensitive information.
  • Speak with the others architects, incite them to share their models, it does not matter if the models are hosted on git or not, but it matters that they are not forgotten on some local drives. (Remind them to tag the sensitive views !)